Loading...
Loading...
Receive and verify GitLab webhooks. Use when setting up GitLab webhook handlers, debugging token verification, or handling repository events like push, merge_request, issue, pipeline, or release.
npx skill4agent add hookdeck/webhook-skills gitlab-webhooksfunction verifyGitLabWebhook(tokenHeader, secret) {
if (!tokenHeader || !secret) return false;
// GitLab uses simple token comparison (not HMAC)
// Use timing-safe comparison to prevent timing attacks
try {
return crypto.timingSafeEqual(
Buffer.from(tokenHeader),
Buffer.from(secret)
);
} catch {
return false;
}
}const express = require('express');
const crypto = require('crypto');
const app = express();
// CRITICAL: Use express.json() - GitLab sends JSON payloads
app.post('/webhooks/gitlab',
express.json(),
(req, res) => {
const token = req.headers['x-gitlab-token'];
const event = req.headers['x-gitlab-event'];
const eventUUID = req.headers['x-gitlab-event-uuid'];
// Verify token
if (!verifyGitLabWebhook(token, process.env.GITLAB_WEBHOOK_TOKEN)) {
console.error('GitLab token verification failed');
return res.status(401).send('Unauthorized');
}
console.log(`Received ${event} (UUID: ${eventUUID})`);
// Handle by event type
const objectKind = req.body.object_kind;
switch (objectKind) {
case 'push':
console.log(`Push to ${req.body.ref}:`, req.body.commits?.length, 'commits');
break;
case 'merge_request':
console.log(`MR !${req.body.object_attributes?.iid} ${req.body.object_attributes?.action}`);
break;
case 'issue':
console.log(`Issue #${req.body.object_attributes?.iid} ${req.body.object_attributes?.action}`);
break;
case 'pipeline':
console.log(`Pipeline ${req.body.object_attributes?.id} ${req.body.object_attributes?.status}`);
break;
default:
console.log('Received event:', objectKind || event);
}
res.json({ received: true });
}
);import secrets
def verify_gitlab_webhook(token_header: str, secret: str) -> bool:
if not token_header or not secret:
return False
# GitLab uses simple token comparison (not HMAC)
# Use timing-safe comparison to prevent timing attacks
return secrets.compare_digest(token_header, secret)For complete working examples with tests, see:
- examples/express/ - Full Express implementation
- examples/nextjs/ - Next.js App Router implementation
- examples/fastapi/ - Python FastAPI implementation
| Event | X-Gitlab-Event Header | object_kind | Description |
|---|---|---|---|
| Push | Push Hook | push | Commits pushed to branch |
| Tag Push | Tag Push Hook | tag_push | New tag created |
| Issue | Issue Hook | issue | Issue opened, closed, updated |
| Comment | Note Hook | note | Comment on commit, MR, issue |
| Merge Request | Merge Request Hook | merge_request | MR opened, merged, closed |
| Wiki | Wiki Page Hook | wiki_page | Wiki page created/updated |
| Pipeline | Pipeline Hook | pipeline | CI/CD pipeline status |
| Job | Job Hook | build | CI job status |
| Deployment | Deployment Hook | deployment | Environment deployment |
| Release | Release Hook | release | Release created |
For full event reference, see GitLab Webhook Events
| Header | Description |
|---|---|
| Secret token for authentication |
| Human-readable event name |
| GitLab instance hostname |
| Unique webhook configuration ID |
| Unique ID for this event delivery |
GITLAB_WEBHOOK_TOKEN=your_secret_token # Set when creating webhook in GitLab# Install Hookdeck CLI for local webhook testing
brew install hookdeck/hookdeck/hookdeck
# Start tunnel (no account needed)
hookdeck listen 3000 --path /webhooks/gitlab// Generated with: gitlab-webhooks skill
// https://github.com/hookdeck/webhook-skills