Consuming Twilio Webhooks: SMS & Voice Status Callbacks and Security

Twilio communicates with your application via HTTP callbacks whenever an incoming SMS arrives, a voice call progresses, or an outbound message transitions status (sent, delivered, undelivered, failed).

Unlike modern JSON-only webhooks, Twilio traditionally sends requests formatted as application/x-www-form-urlencoded.

Key Twilio webhook types

1. Inbound Message & Voice Webhooks: Executed when an SMS or call arrives at your Twilio phone number. Your response must be valid TwiML (<Response><Message>...</Message></Response>).
2. Status Callbacks: Asynchronous notifications sent as messages reach network carrier endpoints (MessageStatus = 'delivered' or 'failed' with ErrorCode).

Verifying X-Twilio-Signature

Twilio uses your Auth Token to calculate an HMAC-SHA1 signature over the full destination URL and alphabetically sorted POST parameters.

Algorithm:

1. Take the full webhook URL exactly as configured in Twilio (including query parameters and HTTPS scheme).
2. If the request is a POST, sort all POST form parameters alphabetically by key.
3. Concatenate each key and value to the URL string without delimiters (e.g. https://example.com/webhookAccountSidAC123From+123456...).
4. Compute the HMAC-SHA1 of this string with your Twilio Auth Token.
5. Base64-encode the result and compare to X-Twilio-Signature.

Debugging Twilio Webhook Errors

• Error 11200 (HTTP retrieval failure): Twilio could not connect to your server within 15 seconds.
• Error 12300 (Invalid Content-Type): Your endpoint returned an unexpected MIME type instead of text/xml for TwiML.

With HookWatch, you can capture every Twilio callback payload, inspect response codes and latency, and replay missed SMS status updates cleanly.