Webhooks
Configure an HTTPS callback URL to receive real-time delivery-status notifications.
Update delivery-status webhook
Replaces the callback URL of the existing delivery-status webhook with a new URL. Use this when your server endpoint changes and you want to redirect notifications without any downtime. The update takes effect immediately: subsequent delivery-status events will be sent to the new URL. The new callback URL is validated exactly as on creation: HTTPS on port 443 or 8443, no credentials, no fragment, and a host resolving to a publicly reachable address. This endpoint does not create a webhook if none exists. If no webhook is currently configured, a 404 is returned; use POST /webhooks/delivery-status to create one 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.
Revoke delivery-status webhook
Permanently removes the configured delivery-status webhook. After deletion, no further delivery-status notifications will be sent to the previously configured URL. The change takes effect immediately. If you need to receive notifications again in the future, you must create a new webhook using POST /webhooks/delivery-status. Any in-flight notification requests that were already dispatched before the deletion may still arrive at the old URL; this is expected and does not indicate an error. Returns 204 on success with no response body. Returns 404 if no webhook is currently configured. Returns 401 if the API key is missing or invalid. Returns 500 if an internal error occurs.
Get delivery-status webhook
Returns the HTTPS callback URL currently configured to receive real-time delivery-status notifications for your account. The platform sends an HTTP POST to this URL every time a delivery-status event occurs for any message sent through your account, across all channels (SMS, RCS, WhatsApp). The same callback URL is shared across all channels; you do not configure separate URLs per channel. Use this endpoint to verify your current webhook configuration before updating or troubleshooting delivery-status callbacks. Returns 404 if no webhook has been configured yet. To set one up, use POST /webhooks/delivery-status. Returns 401 if the API key is missing or invalid. Returns 500 if an internal error occurs.
Configure delivery-status webhook
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.