Test GitLab webhooks
Get a URL for a GitLab project or group webhook, see each event with its X-Gitlab-Event name, check the signing token or secret token, and forward events to your local server. Free, no signup.
Get a webhook URLAdd the URL in GitLab
- Open webhookcat.com, copy your URL and add
/webhooks/gitlabto the end. Sub-paths are kept when requests are forwarded, so this one reaches the route in the code below. - In the project, open Settings, then Webhooks, and select Add new webhook. You need the Maintainer or Owner role.
- Paste your WebhookCat URL as the URL. Select Generate signing token and copy the token, since GitLab shows it only once. Tick the events under Trigger and select Add webhook.
- Send an event with the Test dropdown next to the webhook. A push test needs at least one commit in the project.
What GitLab sends
- X-Gitlab-Event
- The event, such as
Push HookorMerge Request Hook. - webhook-signature
v1,followed by the base64 HMAC-SHA256 of the webhook-id, the webhook-timestamp and the body joined with dots. Sent when the webhook has a signing token, in GitLab 19.0 and later.- webhook-id
- A delivery ID that stays the same on retries and resends.
- webhook-timestamp
- When the request was signed, in Unix seconds.
- X-Gitlab-Token
- The secret token, sent as is, on webhooks that use one instead of a signing token.
- X-Gitlab-Instance
- The GitLab instance, such as
https://gitlab.com.
Check the signature
Open a request in WebhookCat and paste the secret into the Signature box under it. You'll see right away whether it matches. The check runs in your browser, and the secret is never sent or saved.
GitLab's signing token follows the Standard Webhooks spec, so the Signature box is labeled Standard Webhooks. Paste the token you copied when you generated it; GitLab won't show it again, but you can generate a new one. On a webhook with the older secret token, the box compares that token instead.
The same check in your own Node.js server:
import crypto from "node:crypto";
import express from "express";
const app = express();
// The signing token is whsec_ followed by a base64 key.
const token = process.env.GITLAB_SIGNING_TOKEN;
const key = Buffer.from(token.replace(/^whsec_/, ""), "base64");
const raw = express.raw({ type: "application/json" });
// Constant-time comparison; timingSafeEqual needs equal lengths.
const matches = (a, b) => {
const x = Buffer.from(a);
const y = Buffer.from(b);
return x.length === y.length && crypto.timingSafeEqual(x, y);
};
app.post("/webhooks/gitlab", raw, (req, res) => {
const id = req.get("webhook-id");
const ts = req.get("webhook-timestamp");
if (!id || !ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) {
return res.status(400).send("Stale request");
}
const hmac = crypto.createHmac("sha256", key).update(`${id}.${ts}.${req.body}`);
const expected = "v1," + hmac.digest("base64");
const sent = (req.get("webhook-signature") ?? "").split(" ");
if (!sent.some((sig) => matches(sig, expected))) {
return res.status(401).send("Bad signature");
}
console.log(req.get("x-gitlab-event"), JSON.parse(req.body).object_kind);
res.sendStatus(200);
});Forward to your local server
In the inbox you pasted into GitLab, open Share and run the command shown there. It forwards each request to localhost:3000/webhooks/gitlab with the same headers and body, so the signature check in your code passes too. Needs Node.js 22 or later.
$ npx webhookcat listen 3000 --inbox "https://webhookcat.com/#<id>/<key>"Starting from the terminal instead? npx webhookcat listen 3000 creates a new URL and prints it. Paste that URL plus /webhooks/gitlab into GitLab. More in the docs.
Good to know
- GitLab.com waits 10 seconds for a response and counts a 4xx, a 5xx, a timeout or a connection error as a failure.
- After 4 failures in a row the webhook is turned off for a while, starting at one minute and growing up to a day. After 40 it stays off until a test gets a 2xx, so don't leave a 500 response set for long.
- The webhook's Recent events list keeps two days of requests. View details shows each one, and Resend Request sends it again.
- A push that changes more than three branches or tags at once triggers no webhooks by default.