Webhooks

Webhooks notify your application when messages are delivered, fail, or when inbound messages arrive.

Register a Webhook

POST https://api.senderz.com/v1/webhooks

{
  "url": "https://yourapp.com/webhooks/senderz",
  "events": ["message.delivered", "message.failed", "message.received"],
  "secret": "your_signing_secret"
}

Event Types

Event	Description
message.delivered	Message was delivered to the recipient
message.failed	Message delivery failed
message.received	Inbound message received from a recipient

Webhook Payload

{
  "event": "message.delivered",
  "message_id": "01ABCDEF...",
  "from": "+12025551234",
  "to": "+15551234567",
  "channel": "imessage",
  "timestamp": "2026-03-27T10:00:00Z"
}

Inbound message payload:

{
  "event": "message.received",
  "message_id": "01ABCDEF...",
  "from": "+15551234567",
  "to": "+12025551234",
  "body": "Yes, I'd like to confirm my appointment",
  "channel": "imessage",
  "timestamp": "2026-03-27T10:05:00Z"
}

Signature Verification

Every webhook includes an X-Senderz-Signature header. Verify it to ensure the request came from senderZ:

import crypto from 'crypto'

function verifyWebhook(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex')
  return `sha256=${expected}` === signature
}

// In your webhook handler:
const isValid = verifyWebhook(
  JSON.stringify(req.body),
  req.headers['x-senderz-signature'],
  'your_signing_secret'
)

Retry Policy

If your webhook endpoint returns a non-2xx status:

Attempt	Delay
1st retry	2 seconds
2nd retry	4 seconds
3rd retry	8 seconds

After 3 failed retries, the webhook delivery is marked as failed. You can view failed deliveries in the webhook log on your dashboard.

Managing Webhooks

List webhooks:

GET https://api.senderz.com/v1/webhooks

Delete a webhook:

DELETE https://api.senderz.com/v1/webhooks/:id