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.

27 events covered 6 captured samples

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

Signature header
webhook-signature

Also sent: webhook-id, webhook-timestamp.

Scheme
HMAC-SHA256
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}.

How events are identified
x-gitlab-event header
Body format
JSON

Content type: application/json.

Send timestamp
webhook-timestamp
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.

Other headers
x-gitlab-event, x-gitlab-event-uuid, x-gitlab-instance, x-gitlab-token, idempotency-key, x-gitlab-webhook-uuid
Agent skill
npx skills add hookdeck/webhook-skills --skill gitlab-webhooks

Verify GitLab webhooks →

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

  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 →
  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 →
  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 →
  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 →

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

user_add_to_group · user_update_for_group · user_remove_from_group · user_access_request_to_group +5

9 9
collaboration

issue · work_item · note · merge_request +3

7 6
ci

pipeline · build · deployment

3 3
code

push · tag_push · release

3 3
security

access_token · deploy_token · vulnerability

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.

Not affiliated with GitLab. Facts are compiled from public sources and linked inline.