Integrations · Webhooks
Real-time delivery and reply events
Push delivery confirmations, failures, inbound replies, and read receipts to any URL. Every webhook is HMAC-SHA256 signed with a per-tenant secret, retried with exponential backoff, and logged in the portal.
How it works
- Register a webhook URL. Via the API (
POST /v1/webhooks) or the portal. Specify which events to subscribe to. - senderZ sends a POST. When a subscribed event fires, senderZ sends a JSON payload to your URL with the event type, message context, and timestamp.
- Verify the signature. Compute HMAC-SHA256 of the raw body with your secret. Compare to the
X-Senderz-Signatureheader. Reject if they don't match. - Process and return 200. Handle the event in your application and return a 200 status. Non-200 responses trigger automatic retry.
Use cases
Real-time delivery tracking
Build a live dashboard that shows message delivery status as it happens. Subscribe to message.delivered and message.failed events, update your UI in real time via WebSocket or Server-Sent Events.
Inbound reply routing
Route inbound replies to your support queue, CRM, or Slack channel. Subscribe to message.inbound events and dispatch based on the sender number or conversation context.
Compliance audit logging
Subscribe to message.blocked events to track compliance enforcement — STOP opt-outs, quiet-hours rejections, and warming-limit blocks. Write every event to your audit log for regulatory review.
What you get
6 event types
message.sent, message.delivered, message.failed, message.inbound, message.read, message.blocked. Each event includes full message context — ID, channel, recipient, timestamp, and status reason.
HMAC-SHA256 per-tenant signing
Every webhook carries an X-Senderz-Signature header signed with your tenant-specific secret. Verify before processing — the SDK includes a one-line verify helper.
Automatic retry with exponential backoff
If your endpoint returns a non-200 status, senderZ retries up to 5 times with exponential backoff (1s, 2s, 4s, 8s, 16s). After 5 failures, the webhook is marked failed and logged.
Event filtering per webhook
Subscribe each webhook URL to specific event types. A delivery dashboard endpoint only receives message.delivered and message.failed — no noise from inbound or read events.
Webhook logs in portal
Every webhook delivery attempt is logged in the senderZ portal — request payload, response status, latency, and retry count. Debug integration issues without adding logging to your own server.
Frequently asked questions
What is the retry policy?
Up to 5 retries with exponential backoff: 1s, 2s, 4s, 8s, 16s between attempts. If all 5 retries fail, the event is marked as permanently failed and appears in the webhook logs. No event is silently dropped.
How do I verify webhook signatures?
Compute HMAC-SHA256 of the raw request body using your webhook secret, then compare it to the X-Senderz-Signature header. The @senderz/sdk includes a sz.webhooks.verify(signature, body) helper that does this in one call.
Can I filter which events a webhook receives?
Yes. When registering a webhook via the API or portal, specify the events array — e.g., ["message.delivered", "message.failed"]. Only those events will fire to that URL.
What happens if my endpoint is down?
senderZ retries per the backoff schedule. If your endpoint is down for all 5 retries (about 30 seconds total), the event is marked failed. You can replay failed events from the webhook logs in the portal.
Start receiving events
14-day free trial. No credit card.