Work with webhooks

One of the most convenient features of the CLI is the ability to quickly direct Twilio webhooks to a new handler. Both Messaging and Voice are supported.

Update webhook handlers

For example, you can redirect incoming SMS webhooks to the /handle-sms route of your deployed server with:

twilio phone-numbers:update {PHONE_NUMBER_SID|E164} \

Replace {PHONE_NUMBER_SID|E164} with either the SID of your Twilio number (ex. PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX), or the E.164 formatted version of the phone number itself (ex. "+14155552671"). This will set the primary SMS URL for the given Twilio Phone number, and that endpoint will begin handling incoming messages.

Similarly, you can leverage the --voice-url flag to modify your phone number's incoming call handler:

twilio phone-numbers:update {PHONE_NUMBER_SID|E164} \

There are also options for setting the fallback URL and more. Run twilio phone-numbers:update --help for a full list of options.

Proxy your localhost

If you specify a webhook URL that uses the host name localhost or, the CLI will automatically create a public proxy for you using ngrok and set your webhook to direct requests to the new proxy URL. For example:

twilio phone-numbers:update {PHONE_NUMBER_SID|E164} \
  --sms-url http://localhost:3000/handle-sms

This is incredibly handy when trying to prototype an application and validate your webhook handler logic without deploying code to a publicly accessible URL.

Please be aware that this will temporarily expose your computer to the internet. You should exit this command when you have completed testing.

The Webhook plugin

In addition to these built-in features, Twilio Labs has released a CLI plugin to further help you develop and test your webhooks: the Webhook plugin for the Twilio CLI.

Read this excellent introduction blog post to learn more.

Rate this page:

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.

Thank you for your feedback!

Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

Sending your feedback...
🎉 Thank you for your feedback!
Something went wrong. Please try again.

Thanks for your feedback!