---
title: "Delivery Report (DLR) Webhooks"
description: "Handle real-time delivery status callbacks for SMS and WhatsApp messages."
---

# Delivery Report (DLR) Webhooks

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 | 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).