Test Facebook Messenger webhooks locally

Receive Messenger messages on your laptop while you build a bot, with an HTTPS URL Meta can reach.

Before you beginCopy Anchor Link

• Node.js 18 or later
• A Horizon account and the CLI (see Getting started)
• A reserved subdomain for -s. Reserve one on the Subdomains page.
• A Next.js app that uses the App Router and runs on port 3000
• A Meta developer app with the Messenger product, and a Facebook Page connected to it
• A Page access token with the pages_messaging and pages_manage_metadata permissions

import { createHmac, timingSafeEqual } from "node:crypto";

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const mode = searchParams.get("hub.mode");
  const token = searchParams.get("hub.verify_token");
  const challenge = searchParams.get("hub.challenge");

  const isValid =
    mode === "subscribe" && token === process.env.MESSENGER_VERIFY_TOKEN && challenge;
  if (!isValid) {
    return new Response("Forbidden", { status: 403 });
  }

  return new Response(challenge, { status: 200 });
}

export async function POST(request: Request) {
  const appSecret = process.env.MESSENGER_APP_SECRET;
  if (!appSecret) {
    return new Response("Missing MESSENGER_APP_SECRET", { status: 500 });
  }

  const body = await request.text();
  const received = request.headers.get("x-hub-signature-256") ?? "";
  const expected = `sha256=${createHmac("sha256", appSecret).update(body).digest("hex")}`;

  const receivedBuffer = Buffer.from(received);
  const expectedBuffer = Buffer.from(expected);
  const isValid =
    receivedBuffer.length === expectedBuffer.length &&
    timingSafeEqual(receivedBuffer, expectedBuffer);

  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const payload = JSON.parse(body);
  for (const entry of payload.entry ?? []) {
    for (const event of entry.messaging ?? []) {
      console.log(`Received Messenger event from ${event.sender?.id}`);
    }
  }

  return new Response("ok", { status: 200 });
}

MESSENGER_VERIFY_TOKEN=replace-with-a-long-random-string
MESSENGER_APP_SECRET=replace-with-your-app-secret

npm run dev

hrzn tunnel http://localhost:3000 -s my-app

HORIZON: Tunnel connected
  URL          https://my-app.hrzn.run (reserved)
  Forwarding   http://localhost:3000
  Request log  https://hrzn.run/dashboard/tunnels/my-app

curl -X POST "https://my-app.hrzn.run/api/webhooks/facebook-messenger" \
  -H "Content-Type: application/json" \
  -d '{"object": "page", "entry": [{"messaging": [{"message": "TEST_MESSAGE"}]}]}'

Check it worksCopy Anchor Link

When you save the callback URL, the Horizon terminal prints a GET line with status 200.

When someone messages your Page, it prints one POST line:

  POST    200  /api/webhooks/facebook-messenger

Your app terminal prints a line like:

Received Messenger event from 1234567890123456

The number is the sender's page-scoped ID (PSID).

TroubleshootingCopy Anchor Link

Meta can't validate the callback URL or verify tokenCopy Anchor Link

The Horizon terminal shows a GET line with [403], or no line at all.

• Check that MESSENGER_VERIFY_TOKEN is identical to the Verify token you typed in the App Dashboard.
• Check that the callback URL ends with /api/webhooks/facebook-messenger.
• Check that the handler answers with the hub.challenge value and nothing else.
• Restart npm run dev after you edit .env.local.

The signature doesn't matchCopy Anchor Link

The Horizon line shows [401] for a POST request.

• Check that MESSENGER_APP_SECRET is the right secret. Use the App Secret from the app that owns the Messenger product.
• Compute the HMAC over the raw body. Don't run JSON.parse and JSON.stringify first, because that can change the bytes.
• Restart npm run dev after you edit .env.local.

Verification passes but no messages arriveCopy Anchor Link

Your Page isn't subscribed to the app, or the field isn't selected. Send POST /<PAGE_ID>/subscribed_apps?subscribed_fields=messages with a Page access token, and check that messages is subscribed in Products, Messenger, Settings.

The URL changed after a restartCopy Anchor Link

You started the tunnel without -s, so Horizon gave you a new random subdomain. Restart with -s my-app and update the callback URL in the App Dashboard if it differs. -s needs a subdomain you reserved, see Pricing.

Nothing reaches your appCopy Anchor Link

• Check that the Horizon terminal is still running. If its last line is Connection lost. Reconnecting…, wait for Reconnected.
• Check that the npm run dev terminal is running on port 3000.

Next stepsCopy Anchor Link

• Read Meta's Messenger Platform webhooks reference for every field.
• Read Meta's Webhooks getting started for retries and batching.