openwebhook.coOpen inspector →
developer guide

Twilio Status Callback Webhook Example

Twilio message status callback fields, form-encoded body, and a cURL example to inspect MessageStatus deliveries live.

By David Lorenzo García··6 min read

Twilio “status callback” webhooks are not JSON by default. When an SMS or WhatsApp message changes state, Twilio POSTs application/x-www-form-urlencoded fields to the StatusCallback URL. People search for this as “twilio status callback” or “MessageStatus webhook”.

https://hooks.openwebhook.co/YOUR_UUID/twilio

Set StatusCallback on Messages.create, or a Messaging Service callback. Open the inspector first.

Headers and content type

POST /twilio HTTP/1.1
Host: hooks.openwebhook.co
Content-Type: application/x-www-form-urlencoded
I-Twilio-Idempotency-Token: 8c4d2a1b-9e07-4f3c-b6a1-2d9e0f1a3b4c
X-Twilio-Signature: 0a1b2c3d4e5f6789abcdef0123456789abcd==
User-Agent: TwilioProxy/1.1

X-Twilio-Signature is Base64(HMAC-SHA1(url + sorted POST params, auth token)). The signed URL is the public URL Twilio called, including https and query string. A mismatch usually means a proxy rewrote the URL or you parsed the body as JSON.

Form body (MessageStatus=delivered)

AccountSid=ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
ApiVersion=2010-04-01
MessageSid=SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
MessageStatus=delivered
SmsSid=SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa
SmsStatus=delivered
To=whatsapp:+34600000000
From=whatsapp:+14155238886
ToCountry=ES
FromCountry=US
ErrorCode=
ErrorMessage=

Statuses you will see: queued, sent, delivered, undelivered, failed, read (channels that support it). ErrorCode is set on failure (30003, 30005, 30008, …).

The same callback style is used for voice (CallStatus) with different field names. Do not assume JSON.

cURL

curl -X POST \
  'https://hooks.openwebhook.co/YOUR_UUID/twilio' \
  -H 'content-type: application/x-www-form-urlencoded' \
  -H 'x-twilio-signature: test' \
  --data-urlencode 'AccountSid=ACaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  --data-urlencode 'MessageSid=SMaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' \
  --data-urlencode 'MessageStatus=delivered' \
  --data-urlencode 'SmsStatus=delivered' \
  --data-urlencode 'To=whatsapp:+34600000000' \
  --data-urlencode 'From=whatsapp:+14155238886'

In the inspector, open the query and body tabs. The body is form fields, not a JSON object. Copy cURL to hit your handler.

To exercise Twilio’s retry on error, return 500 from a custom Pro response and watch the next MessageStatus attempt.

Related guides