GitLab webhooks
GitLab webhooks are HTTP POST requests that GitLab sends to your URL when something you subscribe to happens in a project or group, such as a push, a merge request or a pipeline status change.
How GitLab webhooks work
Webhooks let your systems react to GitLab as things happen, so you don't have to poll its API. You add a webhook to a project or, on Premium and Ultimate, to a group, then pick the events that trigger it. System hooks are a separate feature for administrators, with their own events.
Each delivery is a JSON POST. The X-Gitlab-Event header names the event type with a value such as Push Hook or Job Hook, and most bodies also carry object_kind, such as push or build. These pages list events by object_kind, or by event_name where a body has no object_kind, and each description gives the header value. GitLab's webhook docs name no version header or field, and payload timestamps moved to ISO 8601 in GitLab 19.0, so don't parse them with a fixed format.
Key facts
{webhook-id}.{webhook-timestamp}.{raw body} The webhook-id header, a literal dot, the webhook-timestamp header, a literal dot, then the raw JSON body as sent. GitLab's docs write this as {message_id}.{timestamp}.{body}.
X-Gitlab-Token A secret token sent as plain text when one is configured, not a signature, so it doesn't protect the body.
x-gitlab-event, x-gitlab-event-uuid, x-gitlab-instance, x-gitlab-token, idempotency-key, x-gitlab-webhook-uuid Setting up GitLab webhooks
- Create a webhook under Settings > Webhooks in a project or group, then set its URL, authentication and trigger events. You need the Maintainer or Owner role on a project, or the Owner role on a group. Select Generate signing token rather than typing a secret token.
- Send a test from the webhook's Test dropdown, which also re-enables a disabled webhook if your endpoint returns a 2xx. To receive deliveries on your own machine, point the webhook at a tunnel such as the Hookdeck CLI.
- Resend a delivery from the webhook's Recent events section, which covers the last two days, or with
POST /projects/:id/hooks/:hook_id/events/:hook_event_id/resend. The project webhooks API lists events from the past 7 days. You can't resend if the webhook's URL has changed.
Delivery behaviour
10 seconds on GitLab.com, where a timeout counts as a failure. Self-managed administrators can change it Retries no schedule documented resend by hand or through the API from the deliveries log After failures disabled after 4 in a row for 1 minute, extending up to 24 hours. After 40 in a row it stays disabled until a test succeeds Duplicates possible after a timeout deduplicate on webhook-id Known failure modes
From Hookdeck's GitLab guide →-
Repeated failures disable the webhook
GitLab temporarily disables a webhook after 4 consecutive failures, and permanently after 40. A 4xx, a 5xx, a timeout or another HTTP error all count, and a permanently disabled webhook stays off until a test request returns a 2xx.
Retries and disabling → -
Slow handlers count as failures
GitLab.com waits 10 seconds for a response and counts a timeout as a failure. Return a 200 or 201 straight away and process the event from a queue.
Handle timeouts → -
The same event can arrive twice
GitLab warns of duplicate events if a webhook times out, and a resend repeats the delivery. Deduplicate on
Handle duplicates →webhook-id, which stays the same across retries. -
Large pushes send nothing
By default, a push that changes more than 3 branches or tags triggers no webhooks at all. Reconcile with the API after bulk operations, or raise
Other limits →push_event_hooks_limiton a self-managed instance.
GitLab webhook best practices
- Use a signing token. A secret token travels as plain text and doesn't protect the body. A signature shows that GitLab sent the delivery and that it wasn't changed.
- Respond within 10 seconds. Return a 200 or 201 and process the event from a queue. On GitLab.com a slower response counts as a failure towards disabling the webhook.
- Watch for disabled webhooks. Check the webhook list for Temporarily disabled and Disabled badges. A webhook stays silent while it's disabled, and after 40 failures it stays that way until you test it.
- Deduplicate on webhook-id.
GitLab warns of duplicates after a timeout.
webhook-idstays the same across retries and resends, so a record of processed IDs stops you handling one twice. - Return a 2xx for events you ignore. Any 4xx counts as a failure, so a 400 for every event you don't handle can disable the webhook. Subscribe only to what you process, and ignore the rest.
- Plan for large pushes. By default a push that changes more than 3 branches or tags triggers no webhooks at all, so reconcile with the API after bulk operations.
Common GitLab webhook events
Code
push | Commits pushed to a branch. Sent as Push Hook. |
tag_push | Tag created or deleted. Sent as Tag Push Hook. |
release | Release created, edited or deleted. Sent as Release Hook. |
Merge requests and issues
merge_request | Merge request opened, changed, merged or closed. Sent as Merge Request Hook. |
issue | Issue opened, edited, closed or reopened. Sent as Issue Hook. |
note | Comment added or edited. Sent as Note Hook. |
CI/CD
pipeline | Pipeline status changes. Sent as Pipeline Hook. |
build | CI job status changes. Sent as Job Hook. |
deployment | Deployment starts, ends, waits or is approved. Sent as Deployment Hook. |
Events by resource
| Resource | Events | Payloads |
|---|---|---|
group | 9 | 9 |
collaboration | 7 | 6 |
ci | 3 | 3 |
code | 3 | 3 |
security | 3 | 3 |
1 more resource, including Other GitLab events. All 27 events →
In this hub
| Webhook events → | Every covered GitLab event, with payloads where the registry has them. |
| MCP events → | How an agent subscribes to GitLab events as MCP events. |
| Verify signatures → | Signature facts, verification code and common failures. |
| Production guide → | Production problems: timeouts, duplicates, ordering and retries, and how to handle them. |
| Agent skill → | Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill gitlab-webhooks |
Keep an outage from disabling your GitLab webhook.
Four failures in a row disable a GitLab webhook. Hookdeck Event Gateway accepts every GitLab delivery, verifies the signature, queues events and retries to your service on your schedule.