Test GitLab Webhooks Locally

From a stuck handler to a live GitLab delivery you can read and replay.

1. 1Start LocalCan and point it at your local server: localcan http 3000. It opens the tunnel and prints your .local domains plus a public HTTPS URL.
2. 2Grab your persistent URL, something like your-app-12.localcan.dev. It is saved to your project file and comes back identical after every restart, so you wire it up once.
3. 3In your project go to Settings → Webhooks (/<group>/<project>/-/hooks) and select Add new webhook. Put your LocalCan URL with your route in URL, e.g. https://your-app-12.localcan.dev/webhook. For authentication pick Signing token → Generate signing token, which hands you a whsec_… value and is the recommended option. Tick what you need in the Trigger section and select Add webhook. Group hooks use the same form at /groups/<group>/-/hooks.
4. 4Open the Test dropdown on the hook and pick an event type. It posts a real payload on demand. Two conditions catch people out: you need the Maintainer or Owner role (Owner for a group hook), and a Push events test needs at least one commit in the project. For something already sent, Recent events → Resend Request repeats it with the same Idempotency-Key.
5. 5Open Inspect Traffic in LocalCan. The delivery lands with full headers and body. Expand it, fix your handler, and hit Replay to send the exact same request again. No new test event needed.

GitLab saysUrl is blocked: Requests to localhost are not allowed

Header

webhook-signature

Algorithm

HMAC-SHA256, base64, formatted v1,<sig> (space-separated list)

What's signed

GitLab signs the string {webhook-id}.{webhook-timestamp}.{raw body}: the webhook-id header, a literal dot, the webhook-timestamp header (Unix seconds), a literal dot, then the exact bytes of the body. The digest is base64-encoded and sent as v1, plus that value. The step almost everyone gets wrong is the key: it is not the token string. Strip the whsec_ prefix and base64-decode the remainder. The header can carry several space-separated signatures for key rotation, so split on spaces and accept a match against any entry. Hash a parsed and re-serialised body and the comparison can never succeed.

Secret

The signing token from the hook form (Settings → Webhooks → Generate signing token, /<group>/<project>/-/hooks), issued with a whsec_ prefix. The older Secret token is a different mechanism: GitLab echoes it verbatim in X-Gitlab-Token with no signing at all, so checking it is a string compare that proves nothing about the body.

import express from 'express'
import crypto from 'node:crypto'

// GitLab publishes Ruby and Python samples only, so this is the Node equivalent.
const SIGNING_TOKEN = process.env.GITLAB_WEBHOOK_SIGNING_TOKEN // whsec_...
const TOLERANCE_SECONDS = 300 // your choice: GitLab says "recent", not how recent

const app = express()

// The digest covers the exact bytes: mount express.raw BEFORE any JSON parser.
app.post('/webhook', express.raw({ type: '*/*' }), (req, res) => {
  const id = req.headers['webhook-id']
  const timestamp = req.headers['webhook-timestamp']
  const signature = req.headers['webhook-signature'] // 'v1,<base64> v1,<base64> ...'
  if (!id || !timestamp || !signature) {
    // Signing token not configured on the hook, or a proxy stripped the headers.
    return res.status(401).send('missing webhook-id / -timestamp / -signature')
  }

  // GitLab asks you to reject stale timestamps yourself to stop replay attacks.
  const skew = Math.abs(Math.floor(Date.now() / 1000) - Number(timestamp))
  if (!Number.isFinite(skew) || skew > TOLERANCE_SECONDS) {
    return res.status(401).send('webhook-timestamp outside tolerance')
  }

  // The key is NOT the token: drop whsec_, base64-decode what is left.
  const key = Buffer.from(SIGNING_TOKEN.replace(/^whsec_/, ''), 'base64')

  // Sign "{id}.{timestamp}.{raw body}" over the original bytes, never a re-stringified object.
  const signed = Buffer.concat([Buffer.from(id + '.' + timestamp + '.'), req.body])
  const expected = crypto.createHmac('sha256', key).update(signed).digest('base64')

  // Space-separated list for key rotation: strip the 'v1,' prefix, match any entry.
  const ok = String(signature)
    .split(' ')
    .some((entry) => {
      const sig = entry.split(',')[1]
      if (!sig || sig.length !== expected.length) return false
      return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))
    })
  if (!ok) return res.status(401).send('signature mismatch')

  const event = req.headers['x-gitlab-event'] // 'Push Hook', 'Merge Request Hook', ...
  const payload = JSON.parse(req.body.toString('utf8')) // payload.object_kind === 'push'

  // Answer inside the timeout: a slow handler counts as a failed delivery.
  res.status(200).send('ok')
  queueWork(req.headers['idempotency-key'], event, payload)
})

The digest itself keeps matching forever. GitLab mixes webhook-timestamp into the signed string, but the timestamp travels in the header beside it, so a captured delivery stays internally consistent and the HMAC still comes out the same next week. What rejects a replay is the freshness check GitLab tells you to write yourself: it publishes no tolerance window, so whatever you chose (300 seconds is the usual pick) is what expires, and nothing on GitLab’s side is enforcing it. Replay promptly, or widen the tolerance in development.