Twilio SMS

The Twilio SMS webhook receives delivery status callbacks for SMS messages sent through Twilio. These updates track whether messages were sent, delivered, or failed.

Endpoint

POST /api/rpc/webhooks/twilio/sms

Signature validation

Twilio signs webhook requests using HMAC-SHA1. The platform validates every request before processing.

Header	Description
X-Twilio-Signature	HMAC-SHA1 signature (base64)

The signature is computed over the full request URL with POST parameters sorted alphabetically and appended. Configure the auth token using the TWILIO_WEBHOOK_AUTH_TOKEN environment variable.

Supported statuses

Twilio Status	Platform Event	Description
sent	sms_sent	Message sent to carrier
delivered	sms_delivered	Message delivered to recipient
failed	sms_failed	Message failed to send
undelivered	sms_undelivered	Message could not be delivered
queued	—	Skipped (message queued)
sending	—	Skipped (message being sent)
receiving	—	Skipped
received	—	Skipped

Payload fields

The callback is sent as form-encoded data with these key fields:

Field	Description
MessageSid	Twilio’s unique message ID
MessageStatus	Current delivery status
To	Recipient phone number
From	Sender phone number
ErrorCode	Twilio error code (if failed)
ErrorMessage	Error description (if failed)
AccountSid	Your Twilio account ID
NumSegments	Number of SMS segments

Response

{
  "success": true,
  "processed": 1
}

Setup

1. In your Twilio console, configure the Status Callback URL on your messaging service or phone number.
2. Set the URL to your platform’s Twilio SMS webhook endpoint.
3. Set the TWILIO_WEBHOOK_AUTH_TOKEN environment variable to your Twilio auth token.

Related pages

• Twilio WhatsApp — WhatsApp delivery status via Twilio
• Webhooks overview — how webhooks work