Skip to main content

Configure delivery-status webhook

POST 
/api/partner-gateway/v1/webhooks/delivery-status

Registers an HTTPS callback URL to receive real-time delivery-status notifications. Once configured, the platform will send an HTTP POST request to your callback URL every time a delivery-status event occurs for messages sent through your account. Events carry statuses such as delivered, expired, undeliverable, and other channel-specific outcomes across SMS, RCS, and WhatsApp. The callback URL must use HTTPS on port 443 or 8443, must carry no credentials and no fragment, and must resolve to a publicly reachable address: URLs pointing at loopback, private, link-local or otherwise internal addresses are rejected with 400, as are hosts that do not resolve. The same URL receives the events of every channel, as JSON objects whose eventType says which kind they are. DELIVERY (SMS, RCS and WhatsApp) is sent when the delivery receipt arrives and carries eventType, channel (SMS, RCS or WHATSAPP), messageId (the customerMessageId you were given at send time), destination, eventDate, price, and the delivery outcome as a numeric statusCode with its description; an SMS event also carries totalParts and numPart, one event per message part. A message still in flight (accepted on SMS, unknown on RCS and WhatsApp) has no receipt yet and produces no event. READ (RCS and WhatsApp) is sent when the recipient opens the message and carries eventType, channel, messageId, destination and eventDate. INBOUND (RCS and WhatsApp) is sent when the recipient writes to you and carries eventType, channel, messageId (the id of the message in the conversation), source (the recipient's number), destination (your WhatsApp number or RCS agent id), receivedDate, messageType, text, and mediaKey for media. Fields without a value are left out. The statusCode values of a DELIVERY event are: 1 accepted (SMS, handed to the carrier with no receipt back yet), 2 rejected (SMS), 3 delivered, 4 expired, 5 deleted (SMS), 6 undeliverable (SMS), 9 general error (RCS and WhatsApp), 10 disabled (RCS and WhatsApp), 11 unsupported (RCS and WhatsApp), 12 conversation closed (WhatsApp), 0 unknown. These are the same codes the Delivery Statuses table in the API overview maps to the deliveryStatus values returned by GET /partner-gateway/v1/messages/status and GET /partner-gateway/v1/messages/history, and the same number the SMS platform's own delivery callback sends as DELIVERY_STATUS. Your server must respond with a 2xx status code within 5 seconds to acknowledge receipt. If your endpoint is unreachable or returns an error, the platform retries the notification up to 5 attempts in all, at least 5 minutes apart for SMS and at least 10 minutes apart for RCS and WhatsApp, for messages sent in the last 10 days. An event can arrive more than once, so process events idempotently. Only one webhook URL can be active per account. If a webhook is already configured, this endpoint returns 409 Conflict. In that case, use PUT /webhooks/delivery-status to update the existing URL, or DELETE /webhooks/delivery-status to remove it first. Returns 400 if the request body is invalid: missing or malformed callbackUrl, a non-HTTPS scheme, a port other than 443 or 8443, or a host that is not publicly reachable. Returns 401 if the API key is missing or invalid. Returns 500 if an internal error occurs.

Request​

Responses​

Webhook configured successfully

Last updated on