Outbound webhooks
An outbound webhook sends Merge Pilot's events to your own systems, such as a SIEM, a ticketing tool or a chat bot of your own, as signed JSON over HTTP. Like every channel's, a webhook delivery is stored, retried until your endpoint accepts it (up to 5 attempts), and kept in the delivery history (see Delivery log and failures).
Setting one up
Company page → Notifications → Notification routes → Add route, then choose the channel Webhook. Company admins of the company and platform admins set it up; it is saved with Save changes (see Saving).
| Setting (label in the UI) | What it does | Default | Allowed values | Who can change it | API field |
|---|---|---|---|---|---|
| Signing secret | The key each request is signed with (see Verifying a request). Write-only: once saved, the field shows Saved; leave empty to keep it | Empty (A long random string) | Any text. Required: a webhook route cannot be saved without one | Company admin, platform admin | notifications.routes[].secret (write-only); has_secret in answers |
| Webhook URL | Your endpoint. Your endpoint gets each event as JSON, signed in the X-MergePilot-Signature header: sha256 HMAC, with the signing secret, of the X-MergePilot-Timestamp header, a dot and the body. See Verifying a request. Write-only, with a Configured / Not configured badge (Leave empty to keep current) | Empty | An http:// or https:// URL, required | Company admin, platform admin | notifications.routes[].webhook_url (write-only); has_webhook_url in answers |
The route's other settings (Route name, Active, Path patterns, Events) work as for any route: see Route settings. Like every route, a webhook route gets each event its events and path patterns match, unless a route above it with Stop here took the event first (see How an event is routed). Send test sends it a test delivery with the event test (see Send test).
Saving a webhook route without a URL or a signing secret is refused: invalid input: webhook route "<name>" needs an http(s) URL and a secret.
Your endpoint may be on your own network. Merge Pilot never calls link-local, multicast or cloud metadata addresses (and normally no loopback address); such a delivery fails with the endpoint's address is not allowed.
Use a long random value as the secret, and change it by typing a new one and saving. Deliveries already waiting are signed with the secret saved at the time of each attempt.
The request
Each delivery is one POST to the route's URL, with the JSON body below and these headers:
| Header | Value |
|---|---|
Content-Type | application/json |
User-Agent | Merge-Pilot-Webhook |
X-MergePilot-Event | The event, such as mr_merged_without_approval (see Events) |
X-MergePilot-Delivery | The delivery's ID. It stays the same on every retry and when the delivery is sent again: use it to ignore a delivery you have already handled |
X-MergePilot-Timestamp | When this attempt was sent, in Unix seconds |
X-MergePilot-Signature | sha256= followed by the hex HMAC-SHA256 signature (see Verifying a request) |
Payload
| Field | Type | Meaning |
|---|---|---|
event | string | The event's API value |
company_id | string | The company's ID |
occurred_at | string | When the event happened (RFC 3339, UTC). The same on every retry |
data.title | string | The title Slack, Teams and email show |
data.message | string | The message Slack, Teams and email show; may span several lines |
data.company | string | The company's slug |
data.project | string | The project's full path; empty when the event is not about a project or the repository is not registered |
data.repo_id | string | The repository's ID in the VCS; empty when the event is not about a repository |
data.mr_number | string | The merge request's (pull request's) number; empty when the event is not about one |
data.vcs_connection_id | string | The ID of the VCS connection the repository belongs to. Left out when there is none |
data.url | string | The page in Merge Pilot the event is about (Open in Merge Pilot). Left out when Merge Pilot's address is not set or the event has no page |
data.mr_id | string | The merge request's ID in Merge Pilot |
data.project_id | string | The project's ID in Merge Pilot |
data.change_approval_key | string | The change approval's key in the tracker |
data.actor | string | Who did it: merged, pushed, approved, declared the emergency, took over, changed the role or removed the protection |
data.branch | string | Direct change to a watched branch, Protection removed from a governed branch: the branch |
data.severity | string | The risk level, or the worst vulnerability severity |
data.policy | string | The policy's name |
data.counts | object | Numbers of the event, such as findings, vulnerabilities and critical, commits, changes (the further direct changes a digest of direct_change sends together), eligible and required, failed_controls, malicious, denied, projects, problems, grants and tokens, days |
data.job_id, data.job_type, data.error_category | string | Background job failed: the job, its type and the kind of failure (never the error itself). error_category is also the kind of failure of Notification not delivered |
data.connection_id, data.problem | string | Connection problem, Connection recovered: the connection and its problem: token_refused, app_permissions, rate_limited or turned_off |
data.due_at | string | Change approval due soon and overdue: the deadline; License expiring: when it expires (RFC 3339, UTC) |
data.user | string | Role changed: whose role |
data.reason | string | VCS access to review: why: deactivated, moved_to_another_company, made_platform_admin, connection_deleted, unlinked, project_removed, company_deactivated |
data.route, data.event | string | Notification not delivered: the route that failed and the event it did not get. A test delivery has route |
The fields from data.url on are left out when they do not apply to the event.
Titles and messages use the VCS's own words (MR !42 on GitLab, PR #42 on GitHub). Every event's title and message are listed in Events.
An example, for a GitLab merge request merged without approval:
{
"company_id": "6718f2c4e1a9b3d5f7a10001",
"data": {
"company": "acme",
"actor": "alice",
"message": "MR !42 (acme/payments) was merged by alice without change-management approval",
"mr_id": "6718f2c4e1a9b3d5f7a10003",
"mr_number": "42",
"project": "acme/payments",
"repo_id": "17",
"title": "MR merged without approval",
"url": "https://merge-pilot.example.com/merge-requests/6718f2c4e1a9b3d5f7a10003",
"vcs_connection_id": "6718f2c4e1a9b3d5f7a10002"
},
"event": "mr_merged_without_approval",
"occurred_at": "2026-10-26T09:14:03.512345Z"
}
The body is fixed when the event happens: a retry or a delivery sent again carries exactly the same bytes.
Verifying a request
The signature proves that the request comes from Merge Pilot and was not changed on the way. It is computed over the timestamp header, a dot and the raw body:
X-MergePilot-Signature = "sha256=" + hex( HMAC-SHA256( key = signing secret,
message = X-MergePilot-Timestamp + "." + raw body ) )
To verify a request:
- Read the raw body as bytes, before any JSON parsing.
- Compute the HMAC-SHA256 of
<X-MergePilot-Timestamp>.<raw body>with the signing secret, in lower-case hex, and putsha256=in front. - Compare it with
X-MergePilot-Signaturein constant time. Refuse the request when they differ. - Refuse a timestamp more than a few minutes away from your clock, so a recorded request cannot be replayed later. Merge Pilot signs every attempt with the time it is sent, so retries pass this check.
- Optionally ignore a
X-MergePilot-Deliveryyou have already handled.
For example, in Python:
import hashlib, hmac, time
def verify(secret: bytes, headers, body: bytes, max_age=300) -> bool:
ts = headers["X-MergePilot-Timestamp"]
expected = "sha256=" + hmac.new(secret, ts.encode() + b"." + body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, headers["X-MergePilot-Signature"]):
return False
return abs(time.time() - int(ts)) <= max_age
Answering
Answer with any 2xx status: the delivery is then delivered. Merge Pilot waits at most 10 seconds for the answer and does not read what the body says.
Any other answer is a failed attempt:
- a
3xxredirect is not followed (the signed request goes only to the route's URL): the endpoint answered 301: redirects are not followed, use the final URL; 4xxand5xx: the endpoint answered 500;- no answer: the endpoint's host name could not be resolved, the endpoint refused the connection, the endpoint's TLS certificate is not trusted, the endpoint did not answer in time, the endpoint's address is not allowed or the endpoint could not be reached.
Retries and delivery history
Webhook deliveries are retried, listed under the route's Recent deliveries and in the Delivery log, and sent again with Send again, as every channel's are: see Delivery log and failures. For a webhook, Send again sends the same body and delivery ID, with a new timestamp and signature, and the history shows the endpoint's answer (, last answer <status>). The deliveries API is described in Delivery log and failures → API; a webhook delivery's body is the JSON sent.
The webhook route itself is set with the company: see Routes → API.
Related pages
Video tutorial
Short videos of this feature working on real GitLab and Jira projects. English audio, English and Turkish subtitles. All video tutorials →