Loading...
Loading...
Learn how to handle Twilio SMS and voice webhooks. Receive incoming messages, respond to calls, and track delivery status in real-time.
Twilio uses webhooks to notify your application about events like incoming SMS messages or phone calls. When an event occurs, Twilio makes an HTTP request to your configured URL with event details. Your server can respond with TwiML instructions.
Triggered when someone sends a text to your Twilio number. Respond with TwiML to send a reply or trigger other actions.
Triggered when someone calls your Twilio number. Respond with TwiML to play audio, gather input, or route the call.
Incoming SMS - New message received on your Twilio numberStatus Callback - Message status updates (queued, sent, delivered, failed)Incoming MMS - Message with media attachmentsIncoming Call - Someone calling your Twilio numberCall Status - Call state changes (ringing, answered, completed)Recording Ready - Call recording is available for downloadTranscription - Speech-to-text transcription completedGo to Webhook.it and copy your unique webhook URL to capture and inspect Twilio requests.
In the Twilio Console, go to Phone Numbers and select your number. Under Messaging or Voice, set your Webhook.it URL for "A MESSAGE COMES IN" or "A CALL COMES IN".
Text or call your Twilio phone number. The webhook will be captured in Webhook.it where you can inspect all the parameters Twilio sends.
Twilio sends webhook data as form-urlencoded POST requests. Here are the key fields:
From - Sender's phone number (+1234567890)To - Your Twilio phone numberBody - The message text contentMessageSid - Unique message identifierNumMedia - Number of media attachments (MMS)FromCity, FromState, FromCountry - Sender locationFrom - Caller's phone numberTo - Your Twilio phone numberCallSid - Unique call identifierCallStatus - Current call state (ringing, in-progress, etc.)Direction - inbound or outboundCallerName - Caller ID name if availableYour webhook can respond with TwiML to instruct Twilio on what to do:
SMS Auto-Reply
<?xml version="1.0" encoding="UTF-8"?> <Response> <Message>Thanks for your message! We'll get back to you soon.</Message> </Response>
Voice IVR Menu
<?xml version="1.0" encoding="UTF-8"?>
<Response>
<Say>Welcome to our support line.</Say>
<Gather numDigits="1" action="/handle-key">
<Say>Press 1 for sales. Press 2 for support.</Say>
</Gather>
</Response>When sending outbound messages or calls, add a statusCallback URL to track delivery status:
queued - Message is queued for sendingsent - Message sent to carrierdelivered - Carrier confirmed deliveryundelivered - Message could not be deliveredfailed - Message failed to sendWhen events occur (incoming SMS, voice calls, delivery status changes), Twilio makes an HTTP request to your configured webhook URL. Your server responds with TwiML instructions telling Twilio what to do next.
Use Webhook.it to capture and inspect Twilio payloads. For local development with TwiML responses, use ngrok or the Twilio CLI which automatically creates a tunnel. Configure the tunnel URL in your Twilio phone number settings.
TwiML (Twilio Markup Language) is XML that tells Twilio how to handle calls and messages. For incoming SMS, respond with <Message> to reply. For calls, use <Say>, <Play>, <Gather>, or <Dial> to control the call flow.
Twilio includes an X-Twilio-Signature header with every request. Use Twilio's SDK RequestValidator to verify the signature using your Auth Token. This ensures requests genuinely come from Twilio.
Webhooks are for incoming events (new SMS received, incoming call). Status callbacks are for tracking outbound message/call status (queued, sent, delivered, failed). Both use HTTP requests but serve different purposes.