Work with webhooks

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

Update webhook handlers

For example, redirect incoming SMS webhooks to the /handle-sms route of your deployed server using your phone number SID:

1twilio phone-numbers:update PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
2  --sms-url http://www.your-server.com/handle-sms

When the update succeeds, you'll see output similar to:

1SID                                 Phone Number  Friendly Name
2PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX  +14155552671  My Phone Number

You can also use the E.164 formatted phone number:

1twilio phone-numbers:update "+18005550100" \
2  --sms-url http://www.your-server.com/handle-sms

(information)

Info

To find your phone number SID, visit the Phone Numbers page in the Twilio Console. Click the phone number you want to update, and you'll see the SID at the top of the page (it starts with PN).

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

1twilio phone-numbers:update PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
2  --voice-url http://www.your-server.com/handle-call

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

Verify the webhook update

To confirm your webhook URL was set correctly, list your phone numbers:

twilio phone-numbers:list

Look for your phone number in the output. You can also check in the Twilio Console to see the updated webhook URLs.

Test the webhook

To test that your webhook is working:

Send a test SMS to your Twilio phone number from your personal phone.
Check your server logs to verify the webhook request was received.

Your server should receive a POST request with parameters like Body, From, To, and more. See the Messaging webhook documentation for the full list of parameters.

Proxy your localhost

(warning)

Warning

The Twilio CLI does not accept localhost or 127.0.0.1 URLs directly. Attempting to use a localhost URL will result in an error: "localhost URLs are not allowed for this operation." You must use a tunneling service like ngrok to create a public URL.

Using ngrok to tunnel your localhost

To test webhooks with your local development server, start ngrok and use the public URL it provides:

Prerequisites:

Download and install ngrok
Sign up for a free ngrok account to get your authtoken
Configure ngrok: ngrok config add-authtoken YOUR_AUTHTOKEN

(information)

Info

Twilio requires a public URL for webhooks because Twilio servers cannot reach your local machine. To test webhooks with your local development server, create a tunnel that makes your localhost accessible from the internet.

Steps:

Start your local server (for example, on port 3000).
In a separate terminal, start ngrok: ngrok http 3000.
Copy the public URL from ngrok (for example, https://abc123.ngrok-free.app).
Update your phone number with the public URL using your phone number SID:

1twilio phone-numbers:update PNXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
2  --sms-url https://abc123.ngrok-free.app/handle-sms

You'll see output confirming the update with your phone number details.

Test by sending an SMS to your Twilio number - watch for the incoming request in both your server logs and the ngrok web interface at http://127.0.0.1:4040

This approach gives you full control over the tunnel. You can see incoming requests in the ngrok dashboard.

(warning)

Warning

Using ngrok or any tunneling service temporarily exposes your computer to the internet. Stop the tunnel when your testing is complete to avoid unintended access.

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.