Test WhatsApp Cloud API webhooks locally

Receive WhatsApp messages and message status updates on your laptop while you build, 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 WhatsApp product and a WhatsApp Business Account
• Permission whatsapp_business_messaging for the messages field, and whatsapp_business_management for the other fields

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.WHATSAPP_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.WHATSAPP_APP_SECRET;
  if (!appSecret) {
    return new Response("Missing WHATSAPP_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 ?? []) {
      const messageCount = change.value?.messages?.length ?? 0;
      console.log(`Received WhatsApp ${change.field} event with ${messageCount} message(s)`);
    }
  }

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

WHATSAPP_VERIFY_TOKEN=replace-with-a-long-random-string
WHATSAPP_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

Check it worksCopy Anchor Link

When you select Verify and save, the Horizon terminal prints a GET line with status 200.

When an event arrives, it prints one POST line:

  POST    200  /api/webhooks/whatsapp

Your app terminal prints a line like:

Received WhatsApp messages event with 1 message(s)

A text message looks like this. Fields can differ for other message types.

{
  "object": "whatsapp_business_account",
  "entry": [
    {
      "changes": [
        {
          "field": "messages",
          "value": {
            "messaging_product": "whatsapp",
            "metadata": { "display_phone_number": "15550783881", "phone_number_id": "106540352242922" },
            "messages": [{ "from": "16505551234", "id": "wamid.…", "timestamp": "1749416383", "type": "text", "text": { "body": "Does it come in another color?" } }]
          }
        }
      ]
    }
  ]
}

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 WHATSAPP_VERIFY_TOKEN is identical to the Verify token you typed in the App Dashboard.
• Check that the callback URL ends with /api/webhooks/whatsapp.
• 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 WHATSAPP_APP_SECRET is the right secret. Use the App Secret from the same app that owns the WhatsApp 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.

Meta retries the same eventCopy Anchor Link

Meta treats any status other than 200 as a failed delivery and retries for up to 7 days. Return 200 fast and do slow work afterwards. Handle duplicates by the message id.

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 WhatsApp Cloud API webhooks guide for every field.
• Read the messages webhook reference for the payload shape.