Message status callback

Payload sent by SignalWire to the status_callback URL each time a message transitions to a new state. The same payload shape is used for Relay SDK message callbacks, SWML send_sms status callbacks, and SWML messaging reply.status_url callbacks.

Configure status_callback when sending a message.

Status callbacks are advisory, best-effort notifications — delivery can be delayed or fail silently, so don’t gate time-critical actions on receiving one. See Status callback reliability.

Payload sent by SignalWire to the `status_callback` URL each time a message transitions to a new state. The same payload shape is used for Relay SDK message callbacks, SWML `send_sms` status callbacks, and SWML messaging `reply.status_url` callbacks. Configure `status_callback` when [sending a message](/docs/apis/rest/messages/create-message). Status callbacks are advisory, best-effort notifications — delivery can be delayed or fail silently, so don't gate time-critical actions on receiving one. See [Status callback reliability](/docs/platform/webhooks#status-callback-reliability).

Payload

The payload of this webhook request is an object.

idstringRequiredformat: "uuid"

The unique ID of the message segment.

project_idstringRequiredformat: "uuid"

The ID of the project the message belongs to.

statusenumRequired

The current delivery state of the message.

tostringRequired

The destination phone number.

fromstringRequired

The source phone number.

bodystringRequired

The message body text.

number_of_segmentsintegerRequired

Number of segments the message body was split into for delivery.

timestampdatetimeRequired

Timestamp of the status transition.

error_codestring or nullRequired

Provider-specific error code if delivery failed. Null when no error occurred.

error_messagestring or nullRequired

Human-readable error message if delivery failed. Null when no error occurred.

custom_variablesobjectOptional

The same custom_variables key/value pairs you supplied when sending the message, echoed back so you can match this callback to a record in your own system. Included only when the message was sent with custom variables.

Response

200

Webhook received

1	{
2	"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
3	"project_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
4	"status": "delivered",
5	"to": "+15551234567",
6	"from": "+15559876543",
7	"body": "Hello World!",
8	"number_of_segments": 1,
9	"timestamp": "2026-03-17T22:26:57Z",
10	"error_code": null,
11	"error_message": null
12	}