Getting Started with Twilio Webhooks
Ready to get started with Twilio webhooks? Our first recommendation is to watch this video on what webhooks are! Prefer to read about them instead of watching a video? Check out this glossary entry: What is a Webhook?
Next, you can follow along with these directions, as we show you how to receive Twilio webhooks with your web application.
This getting started guide is not specific to a certain product at Twilio or to a particular language or platform. We do have language-specific step-by-step tutorials for common webhooks use cases (such as Responding to Incoming Phone Calls, or Tracking Delivery Status of Messages). Other tutorials may be found by choosing the Twilio product from the complete list of tutorials.
Finding the right webhooks
The first step in the process is to find the right webhooks for your application. Specific information about webhooks by product is on these pages:
Other Twilio products (such as Conversations, WhatsApp, and Authy) also have webhooks for certain events.
- Conversations Webhooks
- Authy Webhooks
- Proxy Webhooks
- Video Status Callbacks
- Facebook Messenger
- Message Services
In addition to product-specific webhooks, your web application may receive webhooks from Twilio for events such as an error in TwiML returned by your application, or exceeding a certain number of text messages sent per month. For these webhooks, see these pages in the documentation:
Of course, your project may not need all of these webhooks - but you may be able to add some interesting functionality by using them!
Responding to webhooks
The next step is to map out how you will respond to each webhook. Some Twilio webhooks require a response, typically in Twilio Markup Language (TwiML). The TwiML you send back to the webhook will vary based on what product you are using:
Other Twilio webhooks are informational, and simply require a standard HTTP 200 OK response. This acknowledges that the webhook was received by your web application.
Use mock webhook requests for development
Once you have identified the webhooks you are planning to use, it's time to write some code! For ad-hoc testing purposes during development, you may find it worthwhile to set up mock HTTP requests to your application. We suggest either using a command-line tool like curl, or a desktop application like Postman.
Use the sample webhook requests found in the Twilio documentation as starters for your own requests, or send Twilio webhooks to a service like RequestBin to capture the HTTP request being sent.
Create automated tests for webhooks
After doing some initial validation of your code, you can write automated tests using your preferred testing framework. Once you deploy your application, you can check the Twilio Debugger for errors when a webhook is sent to your application. Those HTTP requests would make excellent candidates for additional tests for your web application framework.
For test-driven development (TDD), you may consider swapping the order of this step and the previous step.
Run your application on a public URL
Twilio needs to send webhook requests to a publicly available URL. There are two main ways of approaching this - the first is to deploy your web application code to a development or test server that is reachable from the public internet. The second way is to use an HTTP tunneling tool like ngrok to set up a public URL for your application (like https://n4f4j12.ngrok.io/) that maps to a web application server running locally on your computer.
In some cases, ngrok or other http tunnels may be blocked by your internal network's firewalls. In those cases, you should set up a development or testing server to use with Twilio before deploying your webhook project to a production environment.
For more about using ngrok to develop webhooks locally, see:
- How to set up your Java and Servlets development environment
- How to set up your C# and ASP.NET MVC development environment
- Set up your Node.js and Express Development Environment
- How to set up your PHP development environment
- How to set up your Python and Flask development environment
- How to set up your Ruby and Sinatra development environment
Configure your public URL with Twilio
Now, Twilio will need to know what URL to send webhooks to. For Twilio phone numbers, you can set the webhook URL for inbound voice calls, SMS messages, or inbound faxes through the Twilio Console.
For other webhooks, such as the delivery status for SMS messages, you will need to set the Callback URL either when you send the message through the REST API or when you provide TwiML as a response. Typically, this is named the callback URL parameter or the status callback URL parameter.
For specific information about how to set the callback URL, see the webhook documentation for that product or type of webhook.
Validate that webhook requests are coming from Twilio
Once you have Twilio sending requests to your web application, you may start validating that your incoming webhooks are actually from Twilio. This ensures that third parties can't issue requests to your webhook URL. Twilio signs each HTTP request to your web application with an
X-Twilio-Signature HTTP header using your Twilio account key.
See the guide to Webhooks Security for more, and read the validating Twilio requests section of the security documentation.
Also, you will need to update your integration tests, if the path they are testing goes through your validation process. One approach would be to sign your HTTP requests with a made-up Twilio account key, and then use that same key to validate requests in the integration test.
Many test frameworks can set environment variables for test mode (as opposed to production), and keeping account credentials outside of your code is also a best practice.
Test your webhooks with live traffic
Everything should work now, but it's time to try some live traffic out! This will depend on which webhooks you are using, but you can start making phone calls to your Twilio number, sending text messages, or whatever else you have built. Try to exercise as many corner or edge cases as possible with your application, so that you can see if there were any assumptions left out of your unit or integration tests. Go in and add those edge cases to your automated tests, while you are doing manual testing.
Promote your web application to staging and production
Now you can start the process of promoting your web application to a staging environment, and then to production. As you enter each step, update the callback URL you use with Twilio to ensure that the testing you are doing goes to the correct environment.
Double check that your production Twilio phone numbers are pointing to production web application environments. Similarly, make sure that the webhooks are being received in production, and network rules don't need to be changed on the firewall.
Test your webhook with SSL enabled, and the certificates you use in production, to ensure that everything works correctly. Twilio webhooks will not work on HTTPS endpoints with self-signed SSL certificates - for more, see the guide to Webhooks Security.
Congratulations! Your web application is in production, and ready to respond to Twilio webhooks! If you run into problems, please visit the Webhooks FAQ.
Need some help?
We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.