Skip to main content
This guide shows you how to use ngrok to receive Twilio SMS webhooks on your localhost app. By integrating ngrok with Twilio, you can:
  • Develop and test Twilio webhooks locally without deploying to a public environment or setting up HTTPS.
  • 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 instead of reproducing events manually in Twilio.
  • Secure your app with Twilio webhook validation provided by ngrok. Invalid requests are blocked by ngrok before reaching your app.

​
What you’ll need

​
1. Start your app

Use an Express app that responds to Twilio webhooks—for example the Twilio SMS webhook sample on GitHub. The handler should respond with TwiML; for more on parsing incoming SMS webhooks in Node.js, see the Twilio blog. Start your app on port 3000. You can confirm it’s running by visiting http://localhost:3000. The endpoint Twilio will call is typically http://localhost:3000/sms (or the path you configured).

​
2. Expose your app with ngrok

Once your app is running locally, you’re ready to put it online securely using ngrok.
The ngrok agent uses your authtoken to authenticate when you start a tunnel.
  • Start ngrok: 
    ngrok http 3000
  • Copy the URL ngrok displays. Your app is now exposed at that URL for use with Twilio (use the full path to your webhook, e.g. https://xxxx.ngrok.app/sms).

​
3. Configure Twilio to send webhooks

Twilio can send webhook requests to your app when it receives an SMS at your Twilio number.
  • Sign in to the Twilio Console.
  • Go to Develop > Phone Numbers > Manage > Active Numbers and select the number to use.
  • Under Messaging, set the webhook URL to your ngrok URL plus the path (e.g. https://xxxx.ngrok.app/sms) and set the type to HTTP Post.
  • Save the configuration.

​
Run webhooks with Twilio and ngrok

Send an SMS to your Twilio phone number. Your app receives the webhook and can respond with TwiML (e.g. a reply about the robots coming). Confirm the request appears in your app logs and in the ngrok inspection UI.

​
Inspecting requests

ngrok’s Traffic Inspector captures all requests made through your ngrok endpoint to your localhost app. Select any request to view detailed information about both the request and response.
To avoid exposing secrets, accounts only collect traffic metadata by default. 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. (Optional) Modify the request: 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.

​
Secure webhook requests

ngrok can verify that incoming requests are from your Twilio account so only that traffic reaches your app.
Webhook verification is limited to 500 validations per month on free accounts. If you need more, you can upgrade to Hobbyist or Pay-as-you-go. See TPU Pricing for details.
ngrok verifies the signature of each request using your Twilio Auth Token, so only traffic from your Twilio account is allowed through.
To add verification:
  • In the Twilio Console, copy your Auth Token (Primary).
  • Create a Traffic Policy file named twilio_policy.yml. Replace {your auth token} with the value you copied: 
    on_http_request:
  - actions:
      - type: verify-webhook
        config:
          provider: twilio
          secret: "{your auth token}"
  • Restart ngrok with the policy file: 
    ngrok http 3000 --traffic-policy-file twilio_policy.yml
  • Send another SMS to your Twilio number to trigger the webhook.
Your app should receive the request and log it in the terminal.