Delivery Report (DLR) Webhooks
Handle real-time delivery status callbacks for SMS and WhatsApp messages.
Last updated · Markdown version
When you set your DLR Webhook URL in the Bulkit dashboard (API Keys -> Webhooks), Bulkit dispatches real-time delivery status updates for all outbound messages.
Events Dispatched
| Event Identifier | Channel | When Dispatched |
|---|---|---|
sms.delivered | SMS | SMS has been delivered to the recipient handset. |
sms.failed | SMS | SMS delivery failed or expired at the network. |
sms.blacklisted | SMS | Recipient has blacklisted the sender ID. |
whatsapp.receipt.updated | WhatsApp message was delivered or read by the recipient. |
1. SMS Delivered (sms.delivered)
JSON
{
"event": "sms.delivered",
"message_id": "451980165",
"internal_message_id": 144,
"outbox_id": "8fa84362-e1a1-4355-89f4-cfbbd2b38031",
"mobile": "254700000001",
"status": "delivered",
"description": "DeliveredToTerminal",
"response_code": "200",
"response_description": "Success",
"delivered_at": "2026-09-19T06:30:15Z",
"blacklisted": false,
"blacklist_reason": "",
"sender_id": 12,
"network_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
"tat": "0.85 sec"
}Payload Fields
| Field | Type | Description |
|---|---|---|
event | string | Constant: sms.delivered. |
message_id | string | External provider message reference ID. |
internal_message_id | integer | Numeric sequence ID if configured. |
outbox_id | string | Unique Bulkit outbox message UUID. |
mobile | string | Recipient phone number (e.g. 254700000001). |
status | string | Delivery status: delivered. |
description | string | Carrier delivery description (e.g. DeliveredToTerminal). |
response_code | string | Provider response code (200 = success). |
delivered_at | string | Timestamp when delivery occurred. |
blacklisted | boolean | Boolean indicating blacklist status (false). |
sender_id | integer/string | Sender ID used for the message. |
tat | string | Turnaround delivery time (e.g. 0.85 sec). |
2. SMS Failed (sms.failed)
JSON
{
"event": "sms.failed",
"message_id": "451980166",
"internal_message_id": 145,
"outbox_id": "18f5d054-9457-410e-a89e-2dc7665fa1a0",
"mobile": "254700000002",
"status": "failed",
"description": "AbsentSubscriber",
"response_code": "500",
"response_description": "Subscriber not reachable",
"delivered_at": null,
"blacklisted": false,
"sender_id": 12
}3. SMS Blacklisted (sms.blacklisted)
When a recipient has opted out or blacklisted the sender ID:
JSON
{
"event": "sms.blacklisted",
"message_id": "452719776",
"outbox_id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
"mobile": "254700000003",
"status": "blacklisted",
"description": "SenderName Blacklisted",
"response_code": "200",
"response_description": "SenderName Blacklisted",
"delivered_at": "2026-09-19T06:31:00Z",
"blacklisted": true,
"blacklist_reason": "SenderName Blacklisted",
"sender_id": 12
}4. WhatsApp Receipt Updated (whatsapp.receipt.updated)
When a WhatsApp message is successfully delivered to the recipient's phone or opened and read:
JSON
{
"event": "whatsapp.receipt.updated",
"message_id": "3EB0C34B8F56D254",
"status": "read",
"chat_jid": "254700000001@s.whatsapp.net",
"timestamp": "2026-09-19T06:32:05Z"
}WhatsApp Statuses
delivered: The message was delivered to the contact's device (double checkmarks).read: The contact opened and viewed the message (blue checkmarks).