Test Facebook webhooks locally

Start your appCopy Anchor Link

This guide uses Page webhooks from the Meta Graph API. The webhook object is page, and the field used here is feed, which fires when something changes on a Page's feed. Meta's other webhook products (Messenger, Instagram, WhatsApp) use the same handshake and signature. See their guides in this section.

Meta checks your endpoint in two ways. First it sends a GET request with the query parameters hub.mode, hub.verify_token and hub.challenge. Your handler compares hub.verify_token with a token you chose and answers with the hub.challenge value. After that, Meta sends event notifications as POST requests. Each one carries an X-Hub-Signature-256 header: sha256= followed by an HMAC SHA-256 (a keyed hash) of the request body, made with your app's App Secret. Read the raw body with request.text() before you parse it, and compare with crypto.timingSafeEqual.

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.FACEBOOK_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.FACEBOOK_APP_SECRET;
  if (!appSecret) {
    return new Response("Missing FACEBOOK_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 change of entry.changes ?? []) {
      console.log(`Received Facebook ${payload.object} event: ${change.field}`);
    }
  }

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

Choose a verify token yourself. It can be any string. Find the App Secret in the App Dashboard under App settings, Basic.

FACEBOOK_VERIFY_TOKEN=replace-with-a-long-random-string
FACEBOOK_APP_SECRET=replace-with-your-app-secret

Start the app on port 3000.

npm run dev

Start a tunnelCopy Anchor Link

Use -s with a subdomain you reserved. Without it, the subdomain is random and changes every run, so the callback URL you saved in Meta would point at a dead URL after a restart. Reserve it first on the Subdomains page. Reserved subdomains are a paid feature, see Pricing.

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

Your public URL is https://my-app.hrzn.run. Meta requires HTTPS, and every Horizon tunnel has it. Keep this terminal open.

Add the webhook in the App DashboardCopy Anchor Link

1. Open your app in the App Dashboard and add the Webhooks product if it isn't there yet.
2. Select the Page object.
3. Set Callback URL to https://my-app.hrzn.run/api/webhooks/facebook.
4. Set Verify token to the same value as FACEBOOK_VERIFY_TOKEN.
5. Select the feed field and subscribe to it. Turn on Include Values if you want the new field values inside the payload.
6. Save. Meta sends the verification GET request to your URL at this point.

Then install your app on the Page. Send POST /<PAGE_ID>/subscribed_apps with subscribed_fields=feed and a Page access token. You can send it from the Graph API Explorer. The feed field needs the pages_manage_metadata and pages_show_list permissions. The person behind the Page access token needs the CREATE_CONTENT, MANAGE or MODERATE task on the Page.

Send a test eventCopy Anchor Link

In the Webhooks product, select Test next to the feed field. A dialog shows sample data. Select Send to My Server to send it to your callback URL.

To send a real event, post on your Page.