Sign in
latestOpenAPI 3.1.0MITraw.githubusercontent.com2026-08-142528921.8 MB

a884f7dcbfc3

Messaging Webhooks

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.

postWebhookmessageStatusCallback

Payload

idstring uuid required

Universal Unique Identifier.

project_idstring uuid required

Universal Unique Identifier.

status'queued' | 'initiated' | 'sent' | 'delivered' | 'undelivered' | 'failed' | 'read' required

Delivery state of a message.

tostring required

The destination phone number.

fromstring required

The source phone number.

bodystring required

The message body text.

number_of_segmentsinteger required

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

timestampstring date-time required

Timestamp of the status transition.

error_codestring nullable required

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

error_messagestring nullable required

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

custom_variablesobject

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.

Example payload

{
  "to": "+15551234567",
  "from": "+15559876543",
  "body": "Hello World!",
  "number_of_segments": 1,
  "timestamp": "2026-03-17T22:26:57Z",
  "custom_variables": {
    "id": "12345",
    "case_number": "54321"
  }
}

Response

Webhook received