Webhooks API
Full reference for webhook configuration endpoints.
GET /api/webhooks
Get your webhook configuration.
Auth: Required
Response 200
{
"dlr_url": "https://yourapp.com/webhooks/sms-dlr",
"mo_url": null,
"signing_secret": "whsec_abc123...",
"is_active": true
}PUT /api/webhooks
Update your webhook configuration.
Auth: Required
Request body
All fields are optional. Omitted fields are unchanged.
{
"dlr_url": "https://yourapp.com/webhooks/sms-dlr",
"is_active": true
}| Field | Type | Description |
|---|---|---|
dlr_url | string | URL to receive delivery report callbacks |
mo_url | string | URL for incoming message (MO) callbacks |
is_active | boolean | Enable or disable webhook delivery |
Response 200
{ "status": "updated" }POST /api/webhooks/rotate-secret
Rotate the HMAC signing secret. Returns the new secret immediately.
Auth: Required
No request body required.
Response 200
{
"signing_secret": "whsec_newxyz789..."
}Update your webhook handler with the new secret before the old one is removed from your handler. The old secret stops working immediately after rotation.
DLR webhook payload
The platform sends POST requests to your dlr_url when a message reaches a terminal state.
{
"event": "message.delivered",
"message_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"status": "delivered",
"phone": "+256712345678",
"sender_id": "eSMSAfrica",
"segments": 1,
"cost": 35.00,
"error_code": null,
"retry_count": 0,
"delivered_at": "2026-05-02T12:00:05Z",
"failed_at": null
}Signature header: X-Webhook-Signature: sha256=<hmac_sha256_hex>
See Webhooks - signature verification for verification examples.
Your endpoint must return HTTP 200 within 15 seconds. Failed deliveries are retried up to 5 times with exponential backoff (10s → 30s → 90s → 4.5min → 13min).