Webhooks

Webhooks let you receive real-time HTTP callbacks when events occur in Smooven, such as notification delivery, opens, clicks, and failures.

Setting up webhooks

Per-notification callbacks

Include a callback_url in any notification request:

{
  "channel": "sms",
  "to": "+61400000000",
  "message": "Your code is 482910",
  "callback_url": "https://your-server.com/webhooks/smooven"
}

Project-level webhooks

Configure a default webhook URL in the dashboard under Settings > Webhooks. This receives events for all notifications in the project.

Webhook payload

{
  "event": "notification.delivered",
  "notification_id": "ntf_abc123",
  "channel_used": "sms",
  "status": "delivered",
  "timestamp": "2026-03-05T08:00:03Z",
  "recipient": {
    "user_id": "user_123",
    "channel_address": "+61400000000"
  }
}

Available events

Event	Description
notification.queued	Notification accepted
notification.sent	Handed to delivery provider
notification.delivered	Confirmed delivery
notification.failed	Permanent failure
notification.fallback	Primary channel failed, trying next
notification.opened	Recipient opened (email, push)
notification.clicked	Recipient clicked a link or action
player.registered	New player registered
player.updated	Player record updated

Verifying signatures

Every webhook request includes an X-Smooven-Signature header. Verify it to confirm the request is authentic:

const crypto = require('crypto');

function verifyWebhook(payload, signature, secretKey) {
  const expected = crypto
    .createHmac('sha256', secretKey)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Retry policy

If your endpoint returns a non-2xx status code, Smooven retries with exponential backoff:

Attempt	Delay
1	5 seconds
2	30 seconds
3	2 minutes

After 3 failed attempts, the event is logged and available in the dashboard under Webhooks > Failed Deliveries.

Best practices

1. Return 200 immediately and process the event asynchronously.
2. Handle duplicates. Use notification_id as an idempotency key.
3. Verify signatures on every request.
4. Monitor failures in the dashboard and set up alerts for repeated failures.