# 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.

Agent skill: `npx skills add hookdeck/webhook-skills --skill gitlab-webhooks` ([details](https://hookdeck.com/webhooks/gitlab/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [GitLab's official docs](https://docs.gitlab.com/user/project/integrations/webhooks/).

[Overview](https://hookdeck.com/webhooks/gitlab) · [Webhook events (27)](https://hookdeck.com/webhooks/gitlab/events) · [MCP events](https://hookdeck.com/webhooks/gitlab/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/gitlab/verify) · [Production guide](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/gitlab/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `webhook-signature` Also sent: webhook-id, webhook-timestamp. | [GitLab docs](https://docs.gitlab.com/user/project/integrations/webhooks/#signing-tokens) |
| Scheme | `HMAC-SHA256` | [GitLab docs](https://docs.gitlab.com/user/project/integrations/webhooks/#signing-tokens) |
| Signed material | `{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}. | [GitLab docs](https://docs.gitlab.com/user/project/integrations/webhooks/#signing-tokens) |
| How events are identified | `x-gitlab-event header` | [GitLab docs](https://docs.gitlab.com/user/project/integrations/webhooks/#delivery-headers) |
| Body format | `JSON` Content type: application/json. | [GitLab docs](https://docs.gitlab.com/user/project/integrations/webhook_events/) |
| Send timestamp | `webhook-timestamp` | [GitLab docs](https://docs.gitlab.com/user/project/integrations/webhooks/#signing-tokens) |
| Legacy signature | `X-Gitlab-Token` A secret token sent as plain text when one is configured, not a signature, so it doesn't protect the body. | [GitLab docs](https://docs.gitlab.com/user/project/integrations/webhooks/#delivery-headers) |
| Other headers | `x-gitlab-event, x-gitlab-event-uuid, x-gitlab-instance, x-gitlab-token, idempotency-key, x-gitlab-webhook-uuid` | [Registry record](https://hookdeck.com/webhooks/gitlab.json) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill gitlab-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/gitlab/skill) |

[Verify GitLab webhooks](https://hookdeck.com/webhooks/gitlab/verify)

## 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](https://docs.gitlab.com/administration/system_hooks/).

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.

## 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](/docs/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

- **Timeout:** 10 seconds. on GitLab.com, where a timeout counts as a failure. Self-managed administrators can change it. [Guide](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#timeouts)
- **Retries:** no schedule documented. resend by hand or through the API from the deliveries log. [Guide](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#retries)
- **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. [Guide](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#retries)
- **Duplicates:** possible after a timeout. deduplicate on `webhook-id`. [Guide](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#duplicates)

## Known failure modes

1. **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](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#retries)
2. **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](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#timeouts)
3. **The same event can arrive twice.** GitLab warns of duplicate events if a webhook times out, and a resend repeats the delivery. Deduplicate on `webhook-id`, which stays the same across retries. [Handle duplicates](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#duplicates)
4. **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 `push_event_hooks_limit` on a self-managed instance. [Other limits](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#other-limits)

From [Hookdeck's GitLab guide](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts).

## GitLab webhook best practices

- **[Use a signing token](https://hookdeck.com/webhooks/gitlab/verify).** 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](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#timeouts).** 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](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#retries).** 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](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#duplicates).** GitLab warns of duplicates after a timeout. `webhook-id` stays the same across retries and resends, so a record of processed IDs stops you handling one twice.
- **[Return a 2xx for events you ignore](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#choosing-events).** 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](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts#other-limits).** 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](https://hookdeck.com/webhooks/gitlab/events#push): Commits pushed to a branch. Sent as Push Hook.
- [tag_push](https://hookdeck.com/webhooks/gitlab/events#tag_push): Tag created or deleted. Sent as Tag Push Hook.
- [release](https://hookdeck.com/webhooks/gitlab/events#release): Release created, edited or deleted. Sent as Release Hook.

### Merge requests and issues

- [merge_request](https://hookdeck.com/webhooks/gitlab/events#merge_request): Merge request opened, changed, merged or closed. Sent as Merge Request Hook.
- [issue](https://hookdeck.com/webhooks/gitlab/events#issue): Issue opened, edited, closed or reopened. Sent as Issue Hook.
- [note](https://hookdeck.com/webhooks/gitlab/events#note): Comment added or edited. Sent as Note Hook.

### CI/CD

- [pipeline](https://hookdeck.com/webhooks/gitlab/events#pipeline): Pipeline status changes. Sent as Pipeline Hook.
- [build](https://hookdeck.com/webhooks/gitlab/events#build): CI job status changes. Sent as Job Hook.
- [deployment](https://hookdeck.com/webhooks/gitlab/events#deployment): Deployment starts, ends, waits or is approved. Sent as Deployment Hook.

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [group](https://hookdeck.com/webhooks/gitlab/events#resource-group) | 9 | 9 |
| [collaboration](https://hookdeck.com/webhooks/gitlab/events#resource-collaboration) | 7 | 6 |
| [ci](https://hookdeck.com/webhooks/gitlab/events#resource-ci) | 3 | 3 |
| [code](https://hookdeck.com/webhooks/gitlab/events#resource-code) | 3 | 3 |
| [security](https://hookdeck.com/webhooks/gitlab/events#resource-security) | 3 | 3 |

1 more resource. [All 27 events](https://hookdeck.com/webhooks/gitlab/events)

## In this hub

- [Webhook events](https://hookdeck.com/webhooks/gitlab/events): Every covered GitLab event, with payloads where the registry has them.
- [MCP events](https://hookdeck.com/webhooks/gitlab/mcp-events): How an agent subscribes to GitLab events as MCP events.
- [Verify signatures](https://hookdeck.com/webhooks/gitlab/verify): Signature facts, verification code and common failures.
- [Production guide](https://hookdeck.com/webhooks/gitlab/guide-auto-disabling-duplicates-retries-timeouts): Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
- [Agent skill](https://hookdeck.com/webhooks/gitlab/skill): Install the webhook skill in your coding agent. `npx skills add hookdeck/webhook-skills --skill gitlab-webhooks`
---

Not affiliated with GitLab. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/gitlab.json) · [Report a correction](https://hookdeck.com/contact)
