Test Intercom webhooks locally

Start your appCopy Anchor Link

Intercom sends the HMAC in X-Hub-Signature as sha1=<40 hex characters>. It uses HMAC SHA1 over the JSON request body, with your app's client secret as the key. Read the body with request.text() before you parse it.

Intercom also sends a HEAD request to validate the URL, so the file exports a HEAD handler.

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

export async function HEAD() {
  return new Response(null, { status: 200 });
}

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

  const body = await request.text();
  const received = request.headers.get("x-hub-signature") ?? "";
  const expected = `sha1=${createHmac("sha1", clientSecret).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 notification = JSON.parse(body);
  console.log(`Received Intercom topic: ${notification.topic}`);

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

Store the client secret in an environment variable.

INTERCOM_CLIENT_SECRET=your-client-secret

Start the app on port 3000.

npm run dev

Intercom gives you five seconds to respond. A late notification counts as failed and is retried once after one minute.

Start a tunnelCopy Anchor Link

Use -s with a subdomain you reserved. Without it, the subdomain is random and changes every run, so your webhook 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-intercom

Horizon prints HORIZON: Tunnel connected. Your public URL is https://my-intercom.hrzn.run. Keep this terminal open.

Add the webhook in IntercomCopy Anchor Link

1. Open your app in the Developer Hub.
2. Under Configure, select Webhooks.
3. Enter https://my-intercom.hrzn.run/api/webhooks/intercom as the endpoint URL. It must be HTTPS.
4. Open the topics dropdown and select the topics you need, for example contact.user.created.
5. Select Save.

Each topic needs a matching permission scope on your app's Authentication page. Removing the scope stops that topic's notifications.

Trigger a notificationCopy Anchor Link

Intercom's docs describe no resend or test button. Trigger a real event instead. With contact.user.created selected, create a user in your Intercom workspace. Pick the action that matches each topic you subscribe to.