Webhooks push real-time updates into your application as messages move through the network, payments confirm and customers reply. This page covers how to wire them up, every status code Sozuri returns synchronously, and the exact JSON payloads you’ll receive on each delivery callback.

• Types of webhooks
• Registering a callback URL
• Anatomy of a webhook request
• Verifying authenticity
• Status codes (synchronous)
• Response envelope per channel
• Delivery callbacks (asynchronous)
• SMS delivery webhook
• WhatsApp delivery webhook
• Premium SMS callbacks
• Cross-channel mapping

Types of webhooks

Registering a callback URL

1. Open your project dashboard.
2. Go to Manage API › Callback URLs › Create new.
3. Paste your HTTPS endpoint in the field for the event type you want (Status, Received Message, Payment, etc.).
4. Save. Your webhook is active immediately — the next event will be delivered to your endpoint.

Anatomy of a webhook request

• Method — always POST
• Content-Type — application/json
• Body — JSON with the event payload (see each channel’s payload below)
• messageId — the same ID returned in the API response when the message was sent
• timestamp — Unix epoch in seconds. Always use this for ordering, not the order of arrival

Verifying authenticity

You can register an Auth Key per callback URL from the dashboard. Sozuri will include it in the body of every request so your server can confirm the call is genuine before processing it.

// Pseudocode
if (request.body.authKey !== process.env.SOZURI_CALLBACK_KEY) {
    return res.status(401).end();
}
// safe to process

Status codes (synchronous)

Every accepted message comes back with a recipients[].statusCode (numeric) and recipients[].status (string). Codes 11–14, 22 and 23 are returned in the immediate response. The rest (15–21) only appear later on your delivery webhook, never in the synchronous response.

Response envelope per channel

Each channel wraps success and error payloads in a slightly different envelope — an artefact of how the underlying providers respond. The table below tells you which fields to parse for the message id, the status, and the error message. Channel-specific error responses are documented on each channel’s own page.

Sample success response (SMS)

{
    "messageData": { "messages": 1 },
    "recipients": [
        {
            "messageId": "MSGBLK6012A7E8B90A21611835368",
            "to": "254700000001",
            "status": "accepted",
            "statusCode": "11",
            "messagePart": 1,
            "type": "bulk"
        }
    ]
}

Sample error response (SMS)

{
    "messageData": {
        "message": "Error. Insufficient balance. Top up and try again."
    }
}

Delivery callbacks (asynchronous)

After Sozuri accepts a message, the final delivery outcome is pushed to your project’s Message Status callback URL. The following sections cover the exact JSON shape per channel and every status string we POST.

1. Match callbacks to your records by messageId. Callbacks can arrive out of order; trust messageId + timestamp, not arrival order.
2. Callbacks are not authenticated by default. Use the optional Auth Key (see above) and ignore any messageId you don’t recognise.
3. No automatic retries. If your endpoint returns a non-2xx or times out, the callback is logged on our side but is not retried.

SMS delivery webhook

Identical shape for Safaricom and Airtel — the only difference is the network field and the values of status.

Payload

POST https://yourdomain.com/your/callback HTTP/1.1
Content-Type: application/json
Accept: application/json

{
    "project": "yourproject_name",
    "messageId": "MSGBLK5F96B6A0CC2EB1603712672",
    "channel": "sms",
    "status": "success",
    "network": "safaricom",
    "type": "bulkDelivery",
    "timestamp": 1603713484
}

Safaricom status values

Safaricom delivery reports are normalised to five strings. The carrier-side deliveryStatus is mapped before reaching your webhook.

Airtel status values

Airtel delivery strings are forwarded as-is from the carrier — no normalisation is applied. The most common values observed in production:

WhatsApp delivery webhook

WhatsApp callbacks fire on every state change reported by Meta. The payload nests the delivery state under a statuses object that mirrors WhatsApp’s own structure.

Payload (successful state change)

{
    "project": "yourproject_name",
    "channel": "whatsapp",
    "phone_number": "254101523135",
    "statuses": {
        "recipient": "254725164293",
        "message_id": "wamid.HBgMMjU0NzI1MTY0Mjkz...",
        "status": "delivered",
        "type": "status",
        "conversation_id": "f659b9ba4d9551c39ca61498126da29f",
        "expiration_timestamp": "1692896813",
        "category": "user_initiated"
    }
}

Payload (failure)

When a message fails, the statuses object replaces conversation metadata with an error string sourced from Meta:

{
    "project": "yourproject_name",
    "channel": "whatsapp",
    "phone_number": "254101523135",
    "statuses": {
        "recipient": "254725164293",
        "message_id": "wamid.HBgMMjU0NzI1MTY0Mjkz...",
        "status": "failed",
        "type": "status",
        "error": "Re-engagement message"
    }
}

WhatsApp status values

Premium SMS callbacks

Premium SMS uses dedicated callback types for subscriber lifecycle events on top of message delivery. The four event types you can receive:

The full Premium callback payloads — including SubscriberLifeCycle field shapes — live on the Subscription premium SMS page.

Cross-channel mapping

If you handle more than one channel, this table lets you normalise the incoming string to a single internal vocabulary: