Test GitLab webhooks locally

Start your appCopy Anchor Link

GitLab signs each delivery with a signing token, following the Standard Webhooks specification. Each request carries three headers: webhook-id, webhook-timestamp and webhook-signature.

The handler rebuilds the signature in four parts:

1. Join the webhook-id value, the webhook-timestamp value and the raw body with dots: {id}.{timestamp}.{body}.
2. Take the signing token, remove the whsec_ prefix and base64-decode the rest. The result is the HMAC key.
3. Compute an HMAC-SHA256 digest of the joined string with that key. Encode it as base64 and prefix it with v1,.
4. Compare the result with each space-separated entry in webhook-signature.

Read the raw body with request.text() before you parse it.

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

const SIGNING_TOKEN_PREFIX = "whsec_";

function isEqual(received: string, expected: string) {
  const receivedBuffer = Buffer.from(received);
  const expectedBuffer = Buffer.from(expected);
  return (
    receivedBuffer.length === expectedBuffer.length &&
    timingSafeEqual(receivedBuffer, expectedBuffer)
  );
}

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

  const body = await request.text();
  const messageId = request.headers.get("webhook-id") ?? "";
  const timestamp = request.headers.get("webhook-timestamp") ?? "";
  const receivedSignatures = (request.headers.get("webhook-signature") ?? "").split(" ");

  const key = Buffer.from(signingToken.replace(SIGNING_TOKEN_PREFIX, ""), "base64");
  const digest = createHmac("sha256", key)
    .update(`${messageId}.${timestamp}.${body}`)
    .digest("base64");
  const expected = `v1,${digest}`;

  const isValid = receivedSignatures.some((signature) => isEqual(signature, expected));
  if (!isValid) {
    return new Response("Invalid signature", { status: 401 });
  }

  const event = request.headers.get("x-gitlab-event");
  console.log(`Received GitLab event: ${event}`);

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

GitLab also tells you to check that webhook-timestamp is recent, to stop replay attacks. Add that check before you go to production.

You get the signing token in a later step. Add a placeholder to .env.local now.

GITLAB_SIGNING_TOKEN=whsec_...

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 GitLab 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-gitlab-app

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

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

Add the webhook in GitLabCopy Anchor Link

1. Open your project in GitLab.
2. In the left sidebar, select Settings > Webhooks.
3. Select Add new webhook.
4. In URL, enter https://my-gitlab-app.hrzn.run/api/webhooks/gitlab.
5. Optional: enter a Name and a Description.
6. Select Generate signing token. GitLab shows the token once, so copy it now. Paste it into .env.local as GITLAB_SIGNING_TOKEN, then restart npm run dev.
7. In the Trigger section, select the events you need.
8. Keep Enable SSL verification checked. Horizon tunnels use HTTPS.
9. Select Add webhook.

Send a test eventCopy Anchor Link

1. In Settings > Webhooks, find your webhook in the list.
2. Open the Test dropdown list.
3. Select the type of event to test.

GitLab doesn't support testing for every event type. GitLab tracks the gaps in issue 379201.

To send an earlier delivery again, select Edit on the webhook. In the Recent events section, select Resend Request on the event. GitLab keeps the last two days of events.