Test CircleCI webhooks locally

Start your appCopy Anchor Link

When you set a secret token on a webhook, CircleCI adds a circleci-signature header to each request. The header holds a comma-separated list of versioned signatures, like v1=<hex>,v2=.... Today v1 is the only version. CircleCI says to check only the latest version, to prevent downgrade attacks.

The v1 value is the HMAC-SHA256 digest of the request body, hex encoded, with your secret token as the key. Read the raw body with request.text().

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

function readSignature(header: string, version: string) {
  const entries = header.split(",").map((entry) => entry.split("=", 2));
  return entries.find(([key]) => key.trim() === version)?.[1]?.trim() ?? "";
}

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

  const body = await request.text();
  const received = readSignature(request.headers.get("circleci-signature") ?? "", "v1");
  const expected = createHmac("sha256", secret).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 event = request.headers.get("circleci-event-type");
  console.log(`Received CircleCI event: ${event}`);

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

Pick a secret and store it in an environment variable. Use a random, high-entropy string.

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

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 your CircleCI 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-circleci-app

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

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

Add the webhook in CircleCICopy Anchor Link

1. In the CircleCI web app, select your organization.
2. Select Projects in the sidebar.
3. Find your project, select the ellipsis, then select Project Settings.
4. In the sidebar, select Webhooks.
5. Select Add Webhook.
6. Enter a Webhook name.
7. Set URL to https://my-circleci-app.hrzn.run/api/webhooks/circleci.
8. Leave Certificate Validation on. Horizon tunnels use HTTPS with a valid certificate.
9. Set Secret token to the same value as CIRCLECI_WEBHOOK_SECRET.
10. Under Select an event, pick at least one event. CircleCI offers workflow-completed and job-completed.

Send a test eventCopy Anchor Link

In the webhook form, select Test Ping Event. CircleCI sends a test event with an abbreviated payload to your URL. You can send it before you save the webhook.

To get a real event, run a workflow in the project. CircleCI sends workflow-completed when the workflow reaches a terminal state, and job-completed for each job.