Skip to main content

Twilio SMS Webhooks

TL;DR

To integrate Twilio webhooks with ngrok:

  1. Start your local twillio webhook app. npm start
  2. Start ngrok. ngrok http 3000
  3. Configure Twilio with your ngrok url and start testing.

This guide covers how to use ngrok to integrate your localhost app with Twilio SMS Webhooks. By integrating ngrok with Twilio, you can:

  • Develop and test Twilio webhooks locally, eliminating the time in deploying your development code to a public environment
  • Secure your app by validating Twilio webhook using ngrok, letting ngrok handle security leaving more time for developing what really matters
  • Inspect and troubleshoot requests from Twilio in real-time via the inspection UI and API
  • Modify and Replay Twilio Webhook requests with a single click and without spending time reproducing events manually in Twilio

Step 1: Start your app​

An example express app can be found on GitHub here: https://github.com/thomas-ngrok/ngrok-example-twilio-sms-webhook.

Loading…

Start your app on port 3000. You can validate it is up and running by visiting http://localhost:3000.

The part we are going to focus on is http://localhost:3000/sms found under /routes/sms.js in the Express example code.

More information on using Twilio webhooks can be found here: https://www.twilio.com/blog/parsing-an-incoming-twilio-sms-webhook-with-node-js

Step 2: Launch ngrok​

Once your app is running successfully on localhost, let's get it on the internet securely using ngrok!

  1. If you're not an ngrok user yet, just sign up to ngrok for free.

  2. Download the ngrok agent.

  3. Go to the ngrok dashboard and copy your Authtoken.
    Tip: The ngrok agent uses the authtoken to log into your account when you start a tunnel.

  4. Start ngrok by running the following command:

    Loading…

  5. ngrok will display a url where your example applicaiton is exposed to the internet (copy this URL for use with Twilio). ngrok agent running

Step 3: Integrate Twilio SMS Webhook​

Now that you have your local environment on the internet, let's configure Twilio to call your code.

  1. Sign in to your Twilio account.
  2. From the Twilio Console, go to Develop > # Phone Numbers > Manage > Active Numbers and select a number to add a webhook to.
  3. At the bottom of the page, under Messaging, (1) add your ngrok url (don't forget to append /sms) under Webhook and (2) change the type to HTTP Post. Twilio SMS Webhook Config Screen
  4. Save the phone number configuration.

Congrats, everything is configured! Now it's time to test.

Run Webhooks with Twilio and ngrok​

  1. Send an SMS message to your Twilio Phone number that was configured in the steps above.
  2. Get excited (and maybe a little scared) when you get a text back saying, "The Robots are coming! Head for the hills!"

Congrats! You got an end-to-end example working but there's even more you can do with ngrok that will make development even easier. Check out how to inspect and replay your requests without having to send an SMS. Trust me, you won't regret it.

Optional next steps​

Add additional security using ngrok's signature webhook verification​

The webhook verification module allows ngrok to assert requests to your endpoint originate from Twillio. This is a quick step to add extra protection to your setup.

Note: This ngrok feature is limited to 500 validations per month on free ngrok accounts. For unlimited, upgrade to Pro or Enterprise.

  1. Login to Twilio Console and copy your Auth Token value.
    Note: ngrok Webhook Verification ensures traffic from your Twilio account is the only traffic allowed to make calls to your app. Because Twilio signs all Webhooks using the Primary Auth Token, ngrok can verifies the signature of every request and only authorizing requests originating from your Twilio account.
  2. Create a file named twilio_policy.yml:
Loading…
  1. Restart ngrok by running the command:
Loading…

Inspecting requests​

ngrok's Traffic Inspector captures all requests made through your ngrok endpoint to your localhost app. Click on any request to view detailed information about both the request and response.

info

By default, accounts only collect traffic metadata to avoid exposing secrets. You must enable full capture in the Observability section of your account settings to capture complete request and response data.

Use the traffic inspector to:

  • Validate webhook payloads and response data
  • Debug request headers, methods, and status codes
  • Troubleshoot integration issues without adding logging to your app

Replaying requests​

Test your webhook handling code without triggering new events from your service using the Traffic Inspector's replay feature:

  1. Send a test webhook from your service to generate traffic in your Traffic Inspector.

  2. Select the request you want to replay in the traffic inspector.

  3. Choose your replay option:

    • Click Replay to send the exact same request again
    • Select Replay with modifications to edit the request before sending

  4. Modify the request (optional): Edit any part of the original request, such as changing field values in the request body.

  5. Send the request by clicking Replay.

Your local application will receive the replayed request and log the data to the terminal.