Receive webhooks

Have the platform POST a signed JSON payload to your URL when something happens in a repository.

Last updated 18 November 2026View as Markdown

The examples use the repository id 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60; replace https://ci.example.com/hooks/git with your endpoint.

Prerequisites

  • An https:// endpoint (any port) on a public address, without a user name or password in the URL. A URL with a literal private address is refused when saved (webhook URL must be a public address); a host name that resolves to a private address is refused at delivery. Redirects are not followed.
  • Permission for git:CreateWebhook on the repository. A repository holds a limited number of webhooks (quota git.webhooks; see Quotas).
  • In the Deutsche Cloud Console, also git:GetRepository to open the repository's settings (without it the page is not found), and git:ListWebhooks to open Webhooks (without it the page shows an access-denied notice).

Add a webhook

  1. In the repository, choose Settings, then Webhooks.
  2. Choose Add webhook.
  3. For Payload URL, enter https://ci.example.com/hooks/git.
  4. (Optional) For Secret, enter a random string. Without a secret, deliveries are not signed.
  5. Under Events, select the events to send. Pushes is selected to begin with.
  6. Leave Active selected.
  7. Choose Create webhook. The webhook is listed with its events, Active, and None yet under Last delivery.

Change a webhook

In the webhook's actions menu, choose Edit, change the fields and choose Save changes; or send PATCH …/webhooks/{hookId} (dcloud git webhooks update, git:UpdateWebhook). Only the fields sent are written, and an empty body is refused with Nothing to update. The secret is write-only and never returned: omitting it (or leaving Secret blank) keeps the stored one, and sending null stops deliveries being signed. isActive: false keeps the hook and stops deliveries.

To delete a webhook, choose Edit, then Delete webhook, and confirm (git:DeleteWebhook, dcloud git webhooks delete).

Deliveries

Method POST, JSON body
Headers X-EWS-Event: <event> · X-EWS-Hook-Id: <webhook id> · X-EWS-Delivery: <id of this delivery, the same on every retry> · X-EWS-Signature-256: sha256=<HMAC-SHA256 of the body with your secret, hex> (only with a secret) · User-Agent: EWS-Git-Webhook
Payload every payload carries event and repository; all but push carry action; issues, issue_comment, pull_request_review and release also carry sender
Timeout 10 seconds per attempt
Retries a 5xx, 408, 429, timeout or connection failure is retried with backoff, 5 attempts in all; any other 4xx fails at once, since the same request would get the same answer

Events

Event Sent when
push any ref is updated, created or deleted, branches and tags alike (ref, before, after, created, deleted)
tag a tag is created or deleted (action: created or deleted); a moved tag sends only push
pull_request action: opened, reopened, synchronize, edited or closed
pull_request_review action: submitted, with the review's state
issues action: opened, edited, closed, reopened, labeled/unlabeled (one per label, with label) or assigned/unassigned
issue_comment action: created, on an issue or in a pull request's conversation (issue.isPullRequest: true); a comment on a line of the diff is not sent
release the same actions as a workflow's on: release: created, published, released, prereleased, edited, deleted
merge_queue action: merged or removed, with the base branch, the pull request, and the landed commit or the removal reason

Verify a delivery

Compute sha256= + HMAC-SHA256(secret, raw body), hex, and compare it to the X-EWS-Signature-256 header in constant time. Verify against the raw body, before parsing it.

Result

Each matching event is delivered to your URL. See View webhook deliveries to check what was sent and what came back.

Did this page help you?