Introduction to Webhooks
To notify your web app when events like incoming phone calls or SMS messages occur, Twilio uses webhooks. While the Twilio REST API handles requests from your app to Twilio, webhooks handle the reverse: requests from Twilio to your app responding to events that Twilio processes.
After certain events occur in Twilio, Twilio sends an HTTP request to a webhook URL you provided to Twilio for your web app. This request is called a webhook or callback. Your web app receives a webhook because a user did something that your app should handle. The Twilio request includes details of the event like the incoming phone number or the body of an incoming message. Many other modern web services like GitHub and Slack also make use of webhooks to communicate events.
Webhook scenario example
After a customer hangs up on a voice call to a customer service phone number that Twilio provides, Twilio can send a webhook to your web app. Your web app could then perform one or more of the following actions:
- Tag the customer service agent who handled that phone call as available.
- Add a record to the customer's profile about the length of the call.
- Prompt the customer service agent to write follow-up notes.
The patterns that some Twilio products vary due to platform or other differences. Services like Twilio use webhooks because your web app doesn't maintain an open session or connection with that service. This results in the service making an asynchronous HTTP request to your app.
Twilio manages two types of webhooks: webhooks for its products and webhooks for runtime.
Each Twilio product handles different events. Twilio Voice, Messaging, Conversations, and Sync each use webhooks differently. To learn more about which webhooks each product uses and how to set them up with your app, see the documentation for that product.
Twilio includes webhooks for events other than product events. When events occur in your app, you can also have Twilio send you webhooks. When Twilio calls your web app, these events include billing levels reaching a thresholdusage-triggers or errors that occur. You can set up a pipeline that sends your webhooks to Slack, Microsoft Teams, or another chat system. You can also set up a webhook that send you email notifications.
Twilio sends some webhooks to ask for instructions. An inbound SMS message to a Twilio phone number triggers a webhook to your web app. Your web app would then return a valid Twilio Markup Language (TwiML) document to the Twilio webhook request with instructions on how to proceed.
Twilio sends other webhooks to provide information. A webhook might notify your web app that a voice recording finished. Twilio doesn't require a response from your web app, other acknowledging receipt.
To get started with Twilio webhooks, see the Getting started with Twilio webhooks guide.
With the Webhooks configuration API, you can control how Twilio authenticates, signs, and delivers each outbound webhook, based on the webhook's URL. With this API, you can do the following:
- Authenticate Twilio to your endpoints with OAuth 2.0, Basic, or Digest credentials.
- Sign requests with a key you manage instead of your account authentication token.
- Set the timeouts, retries, and edge zones Twilio uses and can collect as webhook rules.
To learn more, see how webhooks work, how to validate that inbound webhooks come from Twilio, and answers to common questions.
To implement webhooks and explore their capabilities, follow these tutorials: