Test Instagram webhooks locally

Receive Instagram comments, mentions and messages 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 Instagram API set up
• An Instagram professional account that is public
• An Instagram User access token or Facebook Page token for that account

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.INSTAGRAM_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.INSTAGRAM_APP_SECRET;
  if (!appSecret) {
    return new Response("Missing INSTAGRAM_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 Instagram event: ${change.field}`);
    }
  }

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

INSTAGRAM_VERIFY_TOKEN=replace-with-a-long-random-string
INSTAGRAM_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 save the callback URL, the Horizon terminal prints a GET line with status 200.

When you send the test event, it prints one POST line:

  POST    200  /api/webhooks/instagram

Your app terminal prints a line like:

Received Instagram event: comments

A comment event looks like this. Fields can differ for other events.

{
  "entry": [
    {
      "time": 1520383571,
      "changes": [
        { "field": "comments", "value": { "verb": "update", "object_id": "10211885744794461" } }
      ],
      "id": "10210299214172187"
    }
  ],
  "object": "user"
}

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 INSTAGRAM_VERIFY_TOKEN is identical to the Verify token you typed in the App Dashboard.
• Check that the callback URL ends with /api/webhooks/instagram.
• 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 INSTAGRAM_APP_SECRET is the right secret. With Instagram API with Instagram login, the dashboard shows an Instagram app secret next to the Meta App Secret. Meta's docs say "your app's App Secret" without naming which one, so try the other secret if one fails.
• 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.

Comment or mention webhooks never arriveCopy Anchor Link

Check these three things from Meta's requirements: your app is Live, the Instagram professional account is public, and your app has Advanced Access for the comment or mention permission.

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 Instagram webhooks reference for every field and its permission.
• Read Meta's Webhooks getting started for retries and batching.