> ## Documentation Index
> Fetch the complete documentation index at: https://ngrok.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Twilio SMS Webhooks

> Develop and test Twilio webhooks from localhost.

This guide shows you how to use ngrok to receive [Twilio SMS webhooks](https://www.twilio.com/docs/usage/webhooks/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

* An [ngrok account](https://ngrok.com/signup) and your [authtoken](https://dashboard.ngrok.com/get-started/your-authtoken).
* The [ngrok agent](https://ngrok.com/download) installed.
* An app that handles POST requests (e.g. the [Twilio SMS webhook sample on GitHub](https://github.com/thomas-ngrok/ngrok-example-twilio-sms-webhook) or your own), running on port 3000 with a route such as `/sms`.
* A Twilio account.

## 1. Start your app

Use an Express app that responds to Twilio webhooks—for example the [Twilio SMS webhook sample on GitHub](https://github.com/thomas-ngrok/ngrok-example-twilio-sms-webhook).
The handler should respond with TwiML; for more on parsing incoming SMS webhooks in Node.js, see the [Twilio blog](https://www.twilio.com/blog/parsing-an-incoming-twilio-sms-webhook-with-node-js).

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.

* Copy [your ngrok authtoken](https://dashboard.ngrok.com/get-started/your-authtoken) from the dashboard.

<Tip>
  The ngrok agent uses your authtoken to authenticate when you start a tunnel.
</Tip>

* Start ngrok:

  ```bash theme={null}
  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](https://console.twilio.com/).
* 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](https://dashboard.ngrok.com/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.

<Info>
  To avoid exposing secrets, accounts only collect traffic metadata by default.
  You must enable full capture in the **Traffic Inspector** section of [your account settings](https://dashboard.ngrok.com/settings) to capture complete request and response data.
</Info>

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.

<Note>
  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](/pricing-limits/traffic-policy-unit-pricing/) for details.
</Note>

<Note>
  ngrok verifies the signature of each request using your Twilio Auth Token, so only traffic from your Twilio account is allowed through.
</Note>

To add verification:

* In the [Twilio Console](https://console.twilio.com/), copy your **Auth Token** (Primary).

* Create a Traffic Policy file named `twilio_policy.yml`.
  Replace `{your auth token}` with the value you copied:

  ```yaml theme={null}
  on_http_request:
    - actions:
        - type: verify-webhook
          config:
            provider: twilio
            secret: "{your auth token}"
  ```

* Restart ngrok with the policy file:

  ```bash theme={null}
  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.