Test Sentry webhooks locally

Start your appCopy Anchor Link

Sentry signs every webhook from an integration with your integration's Client Secret. It sends an HMAC (a keyed hash) in the Sentry-Hook-Signature header. The HMAC uses SHA-256 and is a hex digest of JSON.stringify(request.body).

The route handler below parses the body, stringifies it again as Sentry's docs do, and compares the digests with crypto.timingSafeEqual. Sentry also sends the resource type in the Sentry-Hook-Resource header.

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

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

  const body = await request.json();
  const received = request.headers.get("sentry-hook-signature") ?? "";
  const expected = createHmac("sha256", secret)
    .update(JSON.stringify(body), "utf8")
    .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 resource = request.headers.get("sentry-hook-resource");
  console.log(`Received Sentry webhook: ${resource} ${body.action}`);

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

Sentry expects a response within 1 second. Otherwise it counts the request as a timeout. Keep the handler fast.

You get the Client Secret in a later step. Add it to .env.local then.

SENTRY_CLIENT_SECRET=replace-with-your-client-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 Webhook URL in Sentry would point at a dead URL after a restart. Reserved subdomains are a paid feature, see Pricing.

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

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

Your public URL is https://my-sentry-app.hrzn.run. Keep this terminal open.

Create an internal integration in SentryCopy Anchor Link

An internal integration gives one organization signed webhooks. Creating it installs it on your organization.

1. In Sentry, select Settings, then Developer Settings.
2. Select Internal Integration, then Next.
3. Enter a name.
4. Set Webhook URL to https://my-sentry-app.hrzn.run/api/webhooks/sentry.
5. Under Permissions, set Issue & Event to Read & Write.
6. Under Webhooks, select issue.
7. Select Save Changes.
8. Under Credentials, copy the Client Secret into SENTRY_CLIENT_SECRET in .env.local.

Restart npm run dev so Next.js loads the new variable.

To also receive alert notifications, turn on the Alert Rule Action toggle on the integration. The integration then shows up as an action in issue alerts and metric alerts.

Trigger an eventCopy Anchor Link

Cause an event that the integration subscribes to. For the issue resource, create or change an issue in a project, for example by resolving one. Sentry sends one request per event.