Webhooks

Overview

A webhook makes Gitmoap call your own HTTPS endpoint the moment something happens — a push lands, a merge request is merged, a work item closes — so your systems react to the platform instead of polling it. Register one on a single repository or on a whole group, pick the event types you care about, and every matching event arrives as a signed JSON POST within seconds.

Every delivery is recorded. When your receiver was down, or you shipped a bug in it, you can see exactly which deliveries failed and what the response was, and replay any of them once the receiver is healthy again.

Quick start

Before you start

How it works

Where a webhook lives, and how many fire

A webhook belongs to exactly one scope: one repository, or one group. When an event happens in a repository, we deliver it to that repository's own webhooks and to the webhooks of every group above it, all the way to the top of the tree.

A push to acme/platform/api-gateway in the tree above reaches all three. That is the mechanism that makes one group webhook enough for an entire department — and the reason you get three copies of everything if you also register the same endpoint on each repository underneath. Register once, at the highest scope that covers what you want.

Work items are the one case where a group webhook sees something a repository webhook cannot: an epic filed directly in a group has no repository to belong to, so it reaches group webhooks only.

A webhook fires only when it is active and its events list contains the event type. Both filters are applied at delivery time, so pausing a webhook or narrowing its event list takes effect on the next event with no other step.

What you can subscribe to

An events list is built from five names. Each payload names the specific thing that happened in its own action field.

Every payload names its type in an event field and its originator in a sender object. push and merge_request also carry a repository object with the repository's id, name and full path. An issue payload carries scope instead — {"repo": "<id>"} or {"group": "<id>"} — because a work item can belong to either.

Beyond those shared fields, each type carries the subject it is about:

A push payload looks like this:

A ref the push created has an all-zero before, and one it deleted has an all-zero after — that is how a create, an update and a delete are told apart, and it is why a ref_updates entry always carries both. The push payload is also the only one with an event time of its own; date a merge-request or work-item payload from your own receipt.

A sender may be a service account. A bot pushing with its own token is delivered under that account's name and generated email, not under whoever created it — so a receiver that looks the sender up as a person will not find one. Match on the id, or treat an unknown sender as a bot rather than as an error.

The request we send

Every delivery is a POST with a JSON body and these headers:

Deliveries are at-least-once: a rare retry inside the platform can send the same event twice with a different X-Gitmoap-Delivery, and a replay you request yourself always gets a new one. Make your handler idempotent on the content it acts on rather than assuming one delivery per event.

Redirects are not followed. A 301 or 302 from your endpoint is recorded as a failed delivery, so register the final URL rather than a redirecting one.

Retries, and what a delivery record holds

We treat a delivery as transient or final based on what your endpoint does:

Backoff between attempts is 200 ms and then 400 ms, so a refused connection is exhausted in well under a second while an endpoint that accepts the connection and then goes quiet takes the ten-second budget three times over. All three attempts produce one delivery record, describing the last of them — a record marked failed after three tries is one line in the list, not three.

A delivery record holds the event type, whether it succeeded, the response status your endpoint gave, how long we spent on it — every attempt and the waits between them — and when it was triggered. A delivery that never reached your endpoint at all — DNS failure, refused connection, timeout — is recorded as unsuccessful with no status code, which is the fastest way to tell "my endpoint rejected it" apart from "my endpoint was never reached". The full request and response are kept behind the record so a replay can send the original body again; only the outcome comes back over the API.

How to

Register a webhook on a repository

Pick the events, give the endpoint and the secret — all three are required. Pick at least one event type: an empty list is accepted and registers a webhook that is subscribed to nothing. New webhooks are active immediately unless you say otherwise, so have the receiver deployed before you create one — or create it inactive and switch it on afterwards.

The optional name is for you: with several webhooks on one repository, a list of URLs is much harder to read than a list of names like pagerduty and staging-deploy.

Register a webhook on a group

A group webhook covers every repository in the group, including repositories in subgroups, and continues to cover new repositories as they are created. It is the right level for anything that is about the team rather than about one codebase — a chat notifier, an audit sink, a deployment tracker.

Group webhooks are also the only way to receive events for work items filed directly in a group.

Verify the signature on an incoming request

Never act on a request you have not verified. Anyone who learns your endpoint URL can post to it; the signature is what proves the body came from Gitmoap and arrived unmodified.

Worked receivers in two languages are in Examples.

See which webhooks are registered

The list gives each webhook's endpoint, its event types, whether it is active and who created it, newest first. Secrets are never included.

Because a repository is also covered by every group above it, the repository's list is not the whole answer to "what fires on a push here". Check the ancestor groups too when you are chasing a delivery you cannot account for.

Check one webhook's configuration

Send a test delivery

A test posts a small synthetic payload, signed with the real secret and carrying the same headers as a real event. It is the fastest way to prove that the URL resolves, the TLS certificate is trusted and the signature check in your receiver agrees with ours.

The header is X-Gitmoap-Event: push, so a receiver that switches on the event header handles a test along its push path — but the body has no repository, no sender and no ref_updates. Branch on test before you read any of them, or a test delivery crashes the handler it was meant to prove.

A test is sent even when the webhook is paused, and even when its events list does not include push, which is deliberate: it lets you check a new endpoint before you switch it on for real traffic. The call returns as soon as the test is accepted, so a 200 here means "queued", not "your endpoint answered" — the delivery record is where you find out.

Review recent deliveries

Deliveries are listed newest first, fifty at a time unless you ask for a different page size, with a token for the next page.

Scan the status column first. A run of 4xx means your receiver is rejecting us — often a signature check comparing against a re-serialised body. A run of failures with no status at all means we never got a response, so look at DNS, the certificate and the ten-second budget.

Look up a single delivery

Replay a delivery

A replay sends the original body again, under the original event type, with a new delivery id and a fresh signature — computed with whatever secret and posted to whatever URL the webhook holds now. That is what makes it the repair tool after an outage: fix the receiver, then replay the failures without asking anyone to push again.

Replay is not deduplicated — press it twice and your endpoint is called twice, with two different delivery ids. Like a test, a replay is sent even to a paused webhook, and even when the event type has since been dropped from the webhook's events list, so narrowing a subscription does not put the older deliveries beyond replay. The call returns as soon as the replay is accepted rather than when your endpoint answers.

Change what a webhook subscribes to

Every field is individually optional: send only what changes. Sending an events list replaces the list rather than adding to it, so include every type you want to keep.

Rotate the signing secret

Rotation is an edit that sets a new secret; nothing else about the webhook changes, and there is no window in which both secrets are accepted. Sequence it so your receiver is never the odd one out.

The old secret cannot be read back, so if you skip step 2 and the rollout goes wrong, the way out is another rotation rather than a revert.

Pause a webhook without deleting it

Set the webhook inactive. It keeps its endpoint, its secret, its event list and its whole delivery history, and stops receiving events; events raised while it is paused are not queued and do not arrive when you switch it back on. Pausing is the right move for a receiver that is being redeployed, and it is always better than deleting and recreating, which loses the history and the secret.

Delete a webhook

Reference

Limits

Webhooks are capped per repository and per group, and the two budgets are separate — a repository can hold its full allowance while every group above it holds its own, all of which fire on that repository's events.

One over is refused outright, with a message naming the webhook quota. Nothing is half-created and nothing is consumed by the refusal, so a retry after you free a slot behaves exactly as the first attempt would have.

A group's own webhook count is on its usage and limits view, alongside every other cap the group is measured on, so you can see how close you are before a request is refused rather than afterwards. That count covers the webhooks the group itself owns, not those of its subgroups or its repositories. A repository has no such view — count the rows in its webhook list.

Consolidation is usually a better answer than a bigger number: several repository webhooks pointing at one receiver become a single group webhook that also covers repositories created later, and the receiver already knows where an event came from because every payload names its repository or its scope. A receiver that fans out to several internal consumers is one webhook, not several. Where you genuinely need more, an Owner can move the namespace to a higher plan or request an increase on this one limit, which is raisable as far as 5,000.

Troubleshooting

Examples

A Node receiver that verifies and acknowledges

express.raw matters: it hands you the untouched bytes. express.json would parse first, and a signature computed over the parsed-then-reserialised object does not match ours.

A Python receiver

Replaying everything that failed while a receiver was down

Replace <webhook-id> with the id from gitmoap webhooks list. --all follows the pagination cursor and merges every page into one items array, so the loop covers the whole history rather than the newest fifty. Fix the receiver first: a replay against a broken endpoint just adds a second failed delivery for each of the first.

FAQ

Related