> ## 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.

# Facebook Messenger Webhooks

> Develop and test Facebook Messenger webhooks from localhost.

<Note title="Need a different webhook provider?">
  If you don't see your preferred webhook provider, you can [request support for it](https://dashboard.ngrok.com/early-access#webhook-providers).
</Note>

This guide shows you how to use ngrok to receive Facebook Messenger webhooks on your localhost app.

By integrating ngrok with Facebook Messenger, you can:

* Develop and test Facebook Messenger webhooks locally without deploying to a public environment or setting up HTTPS.
* Inspect and troubleshoot requests from Facebook Messenger in real time via the inspection UI and API.
* Modify and replay Facebook Messenger webhook requests with a single click instead of reproducing events manually in your account.
* Secure your app with Facebook Messenger 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.
* [Node.js](https://nodejs.org/) installed (for the sample app, or use your own app).
* A Facebook account.

<Note>
  This integration requires an ngrok Pay-as-you-go plan because Facebook validates your ngrok domain.
</Note>

## 1. Start your app

For this tutorial, you can use the [sample Node.js app on GitHub](https://github.com/ngrok/ngrok-webhook-nodejs-sample).

To install the sample, run the following in a terminal:

```bash theme={null}
git clone https://github.com/ngrok/ngrok-webhook-nodejs-sample.git
cd ngrok-webhook-nodejs-sample
npm install
```

Then start the app:

```bash theme={null}
npm run startFacebook
```

The app runs on port 3000 by default.

You can confirm it's running by visiting `http://localhost:3000`.
The app logs request headers and body in the terminal and shows a message in the browser.

## 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>

* In the dashboard, expand **Gateway** and click **Domains**.

<Tip>
  If you don't have an ngrok Pay-as-you-go plan, subscribe by clicking **Update Subscription** and following the procedure.
</Tip>

* On the **Domains** page, click **+ Create Domain** or **+ New Domain**.
* In the **Domain** pane, enter a value in the **Domain** field (for example, `myexample.ngrok.app`) and click **Continue**.

<Tip>
  Make sure your domain is available.
</Tip>

* Close the **Start a Tunnel** pane and then close the **Domain** pane.

* Start ngrok with your domain:

  ```bash theme={null}
  ngrok http 3000 --url myexample.ngrok.app
  ```

* Copy the URL ngrok displays.
  Your app is now exposed at that URL for use with Facebook Messenger.

## 3. Configure Facebook Messenger to send webhooks

Facebook Messenger can send webhook requests to your app when events occur in your account.
To register for those events you need a Facebook page associated with your account; create one before continuing.

* Sign in to [Meta for Developers](https://developers.facebook.com/).
* Click **My Apps** and then **Create App** on the **Apps** page.
* On **Create an App**, select **Business** and click **Next**.
* On **Provide basic information**, enter a **Display name** (for example, `My Example App`), ensure your email is in **App contact email**, and click **Create App**.

<Tip>
  Facebook may ask for your password in the **Please Re-enter Your Password** popup.
</Tip>

* On the app page, click **Add Product** and then **Set up** inside the **Messenger** tile.
* On **Messenger Settings**, click **Add Callback URL** in the **Webhooks** section.
* In the **Edit Callback URL** popup, enter your ngrok URL with `/webhook` at the end in the **Callback URL** field (for example, `https://myexample.ngrok.app/webhook`).
* Enter `12345` in the **Verify token** field and click **Verify and save**.
* Confirm your localhost app receives the validation post request in the terminal.
* Back on **Messenger Settings**, click **Add or remove Pages** in the **Webhooks** section.
* In the page that opens, sign in to Facebook, select a page, click **Next**, then **Done**, and click **OK** when the link confirmation appears.
* Close the new browser window that shows your Facebook page.
* Under **Messenger** in the left menu, click **Settings**, scroll to **Webhooks**, click **Add subscription** for your page, select all subscription fields, and click **Save**.
* In **Built-in NLP**, select your page in **Select a Page** and turn the slider on.
* At the top of the app page, set **App Mode** to **Live**.

### Run webhooks with Facebook Messenger and ngrok

To trigger webhook calls from Facebook Messenger to your app:

* In [Meta for Developers](https://developers.facebook.com/), go to **Webhooks** under **Products**.
* On the **Webhooks** page, select **Page** in the combo box, find a subscription field you subscribed to, and click **Test**.
* In the **Field Sample** popup, click **Send to My Server**.

Confirm your localhost app receives the test message and logs both headers and body in the terminal.

<Tip>
  Facebook sends different request body contents depending on the events you selected when registering the webhook.
</Tip>

To test with a real message, open the Facebook page you linked to your webhook and send a message to another user.
You can also sign in with another Facebook account, open your page, and send a message via Messenger.

Your app should receive the request and log it in the terminal.

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

To add verification:

* In [Meta for Developers](https://developers.facebook.com/), go to **My Apps**, then **Settings** and **Basic**.

* On the **Basic Settings** page, click **Show** next to **App secret** and copy the value.

* Create a Traffic Policy file named `messenger_policy.yml`.
  Replace `{your app secret}` with the value you copied:

  ```yaml theme={null}
  on_http_request:
    - name: "Facebook Messenger Webhooks"
      actions:
        - type: "webhook-validation"
          config:
            provider: "facebook_messenger"
            secret: "{your app secret}"
  ```

* Restart ngrok with the policy file:

  ```bash theme={null}
  ngrok http 3000 --traffic-policy-file messenger_policy.yml
  ```

* Send a message from the Facebook page linked to your webhook to trigger a request.

Your app should receive the request and log it in the terminal.