Status callbacks and delivery receipts#

DIDWW reports the result of each outbound message to the Callback URL of your HTTP OUT trunk. A status callback reports how DIDWW processed the message. A delivery receipt (DLR) event reports the final delivery status from the carrier.

Processing status and delivery status#

A message passes through three stages, and each stage has its own result:

Stage	Reported by	Result
Submission	The API response	`201 Created` with the message ID. DIDWW accepted the message for processing.
Processing	The message status callback	`Success`, `Routing error`, or `Failed`, with a `code_id` when processing fails.
Delivery	The DLR event callback	The final carrier status, for example `DELIVERED`, `FAILED`, or `EXPIRED`.

A Success processing status means that DIDWW sent the message to the carrier. It does not confirm that the recipient received it. To receive the final delivery status, enable DLR events.

        %%{init: {
  "theme": "base",
  "themeVariables": {
    "fontSize": "14px",
    "actorBkg": "#e0f2fe",
    "actorBorder": "#38bdf8",
    "actorTextColor": "#1f2d3d",
    "actorLineColor": "#38bdf8",
    "signalColor": "#0f766e",
    "signalTextColor": "#1f2d3d",
    "labelBoxBkgColor": "#ccfbf1",
    "labelBoxBorderColor": "#14b8a6",
    "labelTextColor": "#1f2d3d",
    "noteBkgColor": "#fef3c7",
    "noteBorderColor": "#f59e0b",
    "noteTextColor": "#1f2d3d",
    "sequenceNumberColor": "#ffffff"
  }
}}%%

sequenceDiagram
   autonumber
   participant app as Your application
   participant didww as DIDWW
   participant carrier as Carrier
   participant callback as Your Callback URL

   app->>didww: POST /outbound_messages
   didww-->>app: 201 Created with message ID
   didww->>carrier: Route the message
   didww->>callback: Message status callback
   carrier-->>didww: Delivery receipt
   didww->>callback: DLR event callback, when enabled

Callback configuration#

Set the Callback URL in the General settings of your HTTP OUT trunk. DIDWW posts the status callbacks for every message sent through the trunk to this URL.

DIDWW sends each callback as an HTTP POST request with the Content-Type: application/vnd.api+json and User-Agent: DIDWW headers. The body is a JSON:API document.

Configure your firewall to allow requests from the DIDWW callback IP ranges:

IPv4: 46.19.208.0/21, 185.238.173.74/32
IPv6: 2a01:ad00::/32

Callback and delivery receipt payloads#

Message status callback#

Sent as soon as DIDWW finishes processing an outbound message, whether the message was sent to the carrier or failed.

Payload example:

{
  "data": {
    "type": "outbound_message_callbacks",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "time_start": "2025-08-12T12:24:30.45Z",
      "end_time": "2025-08-12T12:24:31.15Z",
      "source": "12125551234",
      "destination": "15551234567",
      "status": "Success",
      "code_id": null,
      "fragments_sent": 1,
      "price": 0.0075
    }
  }
}

Attributes:

Attribute	Description
`id`	The ID of the outbound message. It matches the `id` returned when the message was submitted.
`time_start`	The time message routing started (ISO 8601).
`end_time`	The time message processing finished (ISO 8601).
`source`	The sender of the message. `null` when the request did not include `source` and DIDWW did not select a Sender ID.
`destination`	The recipient’s number.
`status`	The processing status: `Success`, `Routing error`, or `Failed`.
`fragments_sent`	The number of fragments sent. `0` when the message was not sent. See Fragment billing.
`price`	The charge for the message, for all fragments sent. `0.0` when the message was not sent.
`code_id`	The error code if the status is not `Success`. `null` when the message was processed successfully. See Callback error codes.

DLR event callback#

Sent with the final delivery status from the carrier, for example DELIVERED, FAILED, or EXPIRED.

Note

To enable DLR event notifications, contact support@didww.com.

Payload example:

{
  "data": {
    "type": "dlr_event",
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "attributes": {
      "status": "DELIVERED",
      "time_start": "2025-08-12T12:24:32.00Z"
    }
  }
}

Attributes:

Attribute	Description
`id`	The ID of the related outbound message. It matches the `id` of the corresponding `outbound_message_callbacks`.
`status`	The final carrier status, for example `DELIVERED`, `FAILED`, or `EXPIRED`. See Delivery receipt status values.
`time_start`	The time the DLR event was generated (ISO 8601).

Callback examples#

Single SMS callback

If you configure callbacks for your endpoint, the following attributes are returned for each outbound SMS. In some cases, a DLR event callback may also be sent with additional status information.

Unique ID	Time Start	Time End	Source	Destination	Status	Fragments Sent	Price
83950010-3954-43a6-8419-c1417807672f	2023-04-11 09:07:35	2023-04-11 09:07:35	12125551234	15551234567	Success	5	0.0375

Bulk SMS callback

When sending bulk SMS, you receive a callback for every destination number with a unique ID. A DLR event callback may also be sent with final delivery details.

Unique ID	Time Start	Time End	Source	Destination	Status	Fragments Sent	Price
dc38aa6b-c454-438f-9761-e3bdea13bee0	2023-04-11 09:14:30	2023-04-11 09:14:31	12125551234	15551234568	Success	1	0.0075
8075cec0-9fb9-41b6-8580-dabbbb41f0e9	2023-04-11 09:14:30	2023-04-11 09:14:31	12125551234	15551234567	Success	1	0.0075

Delivery behavior and constraints#

If your callback endpoint returns a non-2xx HTTP response or does not respond within 60 seconds, DIDWW retries the callback up to 9 more times:

Callback attempt	Wait interval
2	1 minute
3	10 minutes
4	30 minutes
5	1 hour
6	3 hours
7	6 hours
8	12 hours
9	1 day
10	2 days

Use the message id to match callbacks to your messages, and make your callback handler accept repeated callbacks for the same message.