GitLab webhooks notify your application about repository events, merge requests, pipeline status changes, and issue updates. They support both project-level and group-level configurations for flexible CI/CD integration.
GitLab webhooks are HTTP POST requests that GitLab sends to your server when specific events occur in your account. Rather than continuously polling the GitLab API for updates, webhooks deliver real-time notifications the moment something happens — a payment completes, a user signs up, a deployment finishes, or any other tracked event.
Debugging these webhooks can be challenging because they originate from GitLab's servers, not your browser. You can't simply open DevTools to inspect them. That's where WebhookVault comes in — capture every GitLab webhook, inspect the full payload and headers, and replay them to your local development server.
| Event | Description |
|---|---|
| Push Hook | Fired when commits are pushed to a repository |
| Merge Request Hook | Fired when a merge request is created, updated, or merged |
| Pipeline Hook | Fired when a CI/CD pipeline status changes |
| Issue Hook | Fired when an issue is created, updated, or closed |
Follow these steps to start capturing and debugging GitLab webhooks using WebhookVault.
Sign up for a free WebhookVault API key and create an endpoint to capture GitLab webhooks.
curl -X POST https://webhookvault.anethoth.com/api/v1/endpoints \
-H "Authorization: Bearer wv_your_key" \
-H "Content-Type: application/json" \
-d '{"name": "GitLab Webhooks"}'
# Response:
# {"url": "https://webhookvault.anethoth.com/hook/abc123", "inspect_url": "https://webhookvault.anethoth.com/inspect/abc123"}Go to your GitLab project > Settings > Webhooks Enter your WebhookVault endpoint URL Set a Secret Token for webhook verification Select the trigger events (Push, Merge Request, Pipeline, etc.)
Once GitLab sends a webhook, you can inspect every detail through the WebhookVault API or web inspector.
curl https://webhookvault.anethoth.com/api/v1/endpoints/abc123/requests \
-H "Authorization: Bearer wv_your_key"
# Returns all captured GitLab webhook requests with full headers, body, and metadataReplay any captured GitLab webhook to your local development server for testing.
curl -X POST https://webhookvault.anethoth.com/api/v1/endpoints/abc123/requests/1/replay \
-H "Authorization: Bearer wv_your_key" \
-H "Content-Type: application/json" \
-d '{"url": "http://localhost:3000/webhook"}'
# The original GitLab webhook is replayed to your local serverHere is an example of a typical GitLab webhook payload. Use WebhookVault to capture real payloads from your GitLab account for accurate testing.
{
"object_kind": "merge_request",
"event_type": "merge_request",
"user": {
"username": "admin"
},
"object_attributes": {
"id": 99,
"iid": 1,
"title": "Add new feature",
"state": "opened",
"source_branch": "feature-branch",
"target_branch": "main",
"action": "open"
},
"project": {
"name": "my-project",
"web_url": "https://gitlab.com/user/my-project"
}
}Here are the most common issues developers encounter when working with GitLab webhooks, and how to resolve them.
GitLab sends the secret token in the X-Gitlab-Token header. Compare it directly with your stored secret (no HMAC needed).
GitLab verifies SSL certificates by default. If using self-signed certs, disable SSL verification in webhook settings.
Tag push events are sent as Push Hook events. Check the ref field to distinguish between branch and tag pushes.
Group-level webhooks receive events from all projects in the group. Project webhooks are more specific.
GitLab webhooks are HTTP callbacks that GitLab sends to your server when specific events occur. Instead of polling the GitLab API for changes, webhooks push real-time notifications to your application, making your integration more efficient and responsive.
Use WebhookVault to capture GitLab webhooks in the cloud, then replay them to your localhost. Create a WebhookVault endpoint, configure GitLab to send webhooks to it, and use the replay API to forward captured requests to http://localhost:3000/webhook (or your local port).
Most webhook providers, including GitLab, sign their webhook payloads to prove authenticity. Check the GitLab documentation for the specific signature header and verification algorithm. Use WebhookVault to capture and inspect the raw headers to debug signature verification issues.
Unlike ngrok, WebhookVault captures and stores every webhook request with full headers and payloads. You can replay any GitLab webhook to your local server as many times as needed, inspect historical requests, and share webhook data with your team. No tunnel to maintain or port to expose.
Create a free WebhookVault endpoint in seconds. Capture, inspect, and replay GitLab webhooks with zero configuration.
Get Free API Key