Test Heroku app webhooks locally

Receive Heroku app events on your laptop while you build, with a URL Heroku 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 Heroku app and the Heroku CLI, signed in
• A Next.js app that uses the App Router and runs on port 3000

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

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

  const body = await request.text();
  const received = request.headers.get("heroku-webhook-hmac-sha256") ?? "";
  const expected = createHmac("sha256", secret).update(body).digest("base64");

  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);
  console.log(`Received Heroku event: ${payload.resource} ${payload.action}`);

  return new Response(null, { status: 204 });
}

HEROKU_WEBHOOK_SECRET=replace-with-a-long-random-string

npm run dev

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

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

heroku webhooks:add -a your-heroku-app -i api:release -l notify -s "$HEROKU_WEBHOOK_SECRET" -u https://my-heroku-app.hrzn.run/api/webhooks/heroku

heroku webhooks -a your-heroku-app

heroku webhooks:deliveries -a your-heroku-app
heroku webhooks:deliveries:info DELIVERY_ID -a your-heroku-app

Check it worksCopy Anchor Link

After the release, your Horizon terminal prints one line:

  POST    204  /api/webhooks/heroku

Your app terminal prints:

Received Heroku event: release create

heroku webhooks:deliveries shows the delivery as success. If the line shows [401], see Troubleshooting.

TroubleshootingCopy Anchor Link

The signature doesn't matchCopy Anchor Link

The Horizon line shows [401]. Check these in order:

• HEROKU_WEBHOOK_SECRET is the secret you passed to -s, or the one Heroku printed. They must match exactly.
• The handler encodes the digest as base64. Hex encoding fails.
• The handler hashes the raw body. Don't run JSON.parse and JSON.stringify first, because that can change the bytes.
• You restarted npm run dev after you edited .env.local.

Heroku retries and delays other notificationsCopy Anchor Link

With -l sync, Heroku retries failed deliveries for up to 72 hours. Heroku delivers notifications in order, so a failing endpoint delays the next ones. Fix the endpoint, or switch to -l notify while you develop.

The URL changed after a restartCopy Anchor Link

You started the tunnel without -s, so Horizon gave you a new random subdomain. Heroku still sends events to the old URL. Restart with -s my-heroku-app and the URL stays the same. -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 -u URL ends with /api/webhooks/heroku.
• Check that the event you trigger matches an entity in -i.
• Run heroku webhooks:deliveries to see whether Heroku tried.

Next stepsCopy Anchor Link

• Read Heroku's app webhooks article for the full list of events.
• Use the -t flag to add a custom Authorization header, if you want a second check.