> For the complete documentation index, see [llms.txt](https://wiki.mobivatebulksms.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://wiki.mobivatebulksms.com/overview/introduction/delivery-notifications-dlrs-webhooks.md).

# Delivery Notifications (DLRs / Webhooks)

## Delivery Notifications

Mobivate provides delivery notifications for SMS messages as their delivery status changes. These notifications allow you to track message progress and final delivery outcomes.

### How Delivery Notifications Work

* Delivery notifications are sent on **every status change**, except when a message is initially created.
* Notifications are delivered asynchronously to your configured **Delivery Endpoint (webhook)**.
* Each notification contains the latest known status for the message.

### Configuring the Delivery Endpoint

You can define a delivery notification endpoint in two ways:

#### 1. API Key Default (Recommended)

Set a default Delivery Endpoint URL for an API key in the Mobivate user interface.\
This endpoint will be used for all messages sent using that key.

{% hint style="info" %}
To configure a webhook via API key, please see [**Creating a new API Key**](/overview/introduction/creating-a-new-api-key.md).
{% endhint %}

#### 2. Per-Request Override

You can override the default endpoint by supplying a `callbackURL` parameter when sending:

* Single messages
* Batch campaigns
* Template-based campaigns
* Alias-based messages

This allows fine grained control over where delivery notifications are sent.

### Delivery Notification Format

Delivery notifications are sent in **XML format by default**.

To receive the delivery notification in **JSON format**, append `?json` to the callback URL.

For example:

```
https://example.com/delivery?json
```

**XML Response**

The default XML delivery notification has the following format:

```xml
<deliveryreceipt>
    <created>2026-09-18T09:06:51.352Z</created>
    <deliveryMessageId>8bbe5414-2813-4616-981a-XXXXXXXXXXXX</deliveryMessageId>
    <status>DELIVERED</status>
    <statusCode>1</statusCode>
    <part>1</part>
    <parts>1</parts>
</deliveryreceipt>
```

**JSON Response**

When `?json` is appended to the callback URL, the delivery notification is returned in JSON format:

```json
{
    "batchId": null,
    "clientReference": null,
    "created": "2026-09-18T09:16:37.836Z",
    "deliveryMessageId": "898971db-d4df-44d6-a6d7-XXXXXXXXXXXX",
    "part": 1,
    "parts": 1,
    "status": "DELIVERED",
    "statusCode": 1
}
```

#### Delivery Notification Fields

| Field             | Type                       | Description                                                          |
| ----------------- | -------------------------- | -------------------------------------------------------------------- |
| batchId           | string / null              | The batch campaign identifier, if applicable.                        |
| clientReference   | string / null              | The client reference associated with the message, if provided.       |
| created           | string (ISO 8601 datetime) | The date and time the delivery notification was created.             |
| deliveryMessageId | string (UUID)              | The unique identifier for the delivered message.                     |
| status            | string                     | The current delivery status of the message, for example `DELIVERED`. |
| statusCode        | integer                    | The numeric code representing the delivery status.                   |
| part              | integer                    | The current message part number.                                     |
| parts             | integer                    | The total number of parts in the message.                            |

{% hint style="info" %}
Delivery notifications are sent to your configured endpoint using an HTTP **`POST`** request. When `?json` is appended to the callback URL, the request body contains the delivery notification in JSON format. Without `?json`, the notification is sent in XML format.
{% endhint %}

### Best Practices

* Always return a <mark style="color:$success;">**`200 OK`**</mark> response from your endpoint to acknowledge receipt.
* Process notifications asynchronously on your side.
* Store delivery receipts for auditing and reporting purposes.
* Ensure your endpoint is publicly accessible and secured.

{% hint style="warning" %}
Delivery notifications are sent independently of message submission.
{% endhint %}