Volley / Templates / Twilio incoming SMS
Webhooks templateTwilio incoming SMS webhook, as a sequence diagram
A text message arrives, Twilio posts it to your app, and your TwiML answer becomes the reply. The form fields, the signature and both replies are on their arrows.
Click any arrow in the editor to see its request and response as a table or the raw body. Change the hosts, ids and fields to match your integration, then share a link or embed it in your README.
Step by step
- Someone texts your Twilio number.
- Twilio posts to your webhook, form encoded, with
From,To,Body,MessageSidand anX-Twilio-Signatureheader. - Your app validates the signature and does its work.
- Your app answers with TwiML. A
<Message>in the response becomes the reply text.
Easy to get wrong
- The signature covers the exact URL Twilio called, so a proxy that changes the scheme or host breaks validation.
- Answer with
Content-Type: text/xml. An empty<Response/>sends no reply. - Twilio sends the body form encoded, not JSON.
The source
The whole diagram is this plain text. Copy it into your repo, or open it in the editor.
twilio-sms-webhook.volley
title: Twilio incoming SMS webhook
order: Phone, Twilio, App
Phone -> Twilio: SMS "STATUS 1042" to +1 415 555 0100
Twilio -> App: POST /sms
in: Webhook request
```http
POST /sms HTTP/1.1
Content-Type: application/x-www-form-urlencoded
X-Twilio-Signature: <redacted>
MessageSid=SM2b1f0c7e9a4d4e8f8b5a6c3d2e1f0a9b&AccountSid=AC0123456789abcdef0123456789abcdef&From=%2B14155550123&To=%2B14155550100&Body=STATUS+1042&NumMedia=0
```
note: Validate `X-Twilio-Signature`: a base64 HMAC-SHA1 of the full webhook URL followed by every POST parameter, sorted by name, keyed with your auth token.
App -> App: Look up order 1042
if: Order found
App --> Twilio: 200 OK
out: TwiML reply
```http
HTTP/1.1 200 OK
Content-Type: text/xml
<Response><Message>Order 1042 shipped today. Tracking 1Z999AA10123456784.</Message></Response>
```
else: Unknown order
App --> Twilio: 200 OK
out: TwiML reply
```http
HTTP/1.1 200 OK
Content-Type: text/xml
<Response><Message>We could not find order 1042. Reply HELP for options.</Message></Response>
```
end
Twilio -> Phone: Reply SMS
note: Twilio sends whatever the `<Message>` says. An empty `<Response/>` sends nothing.