Skip to main content
SMS webhooks notify your system about the delivery status of the messages you send: when an SMS is delivered, undelivered or expires. The product is outbound-only — there are no inbound SMS events.

The two channels

There are two independent webhook channels, which can be used together or separately.
Configured once per account in the Dashboard. It fires for all sends of the account (single API sends, bulk campaigns and flows), regardless of the campaign. Use it when a single endpoint centralizes the status of everything the account sends.
Configured on the bulk campaign itself. It fires only for that campaign’s recipients. Use it to route the status of a specific campaign to a dedicated endpoint.
The sms.sent event is not delivered to webhooks: billing and acceptance happen at send time, so only final status events are notified. The product is outbound-only — there is no inbound SMS event.

Envelope — account webhook

The account webhook sends the event content inside data, together with channel and timestamp at the root level.
string
required
Event name (e.g. sms.delivered). See Events.
string
required
Source channel. Always "sms".
object
required
Delivery details. See the Events page for each field.
string
required
Time the webhook was sent, in ISO 8601 (UTC).

Envelope — campaign webhook

The campaign webhook is flat: the fields sit at the root level and it includes campaignId and recipientId for correlation.
string
required
Event name (e.g. sms.delivered).
string
required
ID of the campaign that originated the send.
string
required
ID of the recipient within the campaign.
string
required
Destination number in E.164 format.
string
required
Resulting delivery status. See Events.
string | null
required
Normalized error code in case of failure, or null. See the code table in Events.
number
required
Number of SMS segments (parts).
string
required
Time of the event in ISO 8601 (UTC).

Headers

X-DAPI-Signature is only sent when a secret is configured. It is the HMAC-SHA256, in hexadecimal, of the request’s raw body.
The X-DAPI-Webhook-Channel header is sent only in the account webhook. The campaign webhook sends only Content-Type (plus any custom headers configured on the campaign) and, when a secret is set, X-DAPI-Signature.

Validating the signature

Compute the HMAC over the raw body received (not over re-serialized JSON) and compare it with the header using a constant-time (timing-safe) comparison:

Delivery and reliability

The delivery guarantee differs between the two channels.
Delivered through a durable queue, with retries, a per-URL circuit breaker and delivery logs (webhook_logs). In case of a temporary failure, delivery is retried automatically.
Delivered by a single HTTP call without retries (fire-and-forget). If the endpoint is unavailable at that moment, the event is not resent.
Since the campaign webhook has no retries, make sure the endpoint responds quickly and is available. For reliable delivery, prefer the account webhook.

Next steps

See the list of events, the resulting status of each one and the normalized error codes in Events.