Receive webhooks
Have the platform POST a signed JSON payload to your URL when something happens in a repository.
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:CreateWebhookon the repository. A repository holds a limited number of webhooks (quotagit.webhooks; see Quotas). - In the Deutsche Cloud Console, also
git:GetRepositoryto open the repository's settings (without it the page is not found), andgit:ListWebhooksto open Webhooks (without it the page shows an access-denied notice).
Add a webhook
- In the repository, choose Settings, then Webhooks.
- Choose Add webhook.
- For Payload URL, enter https://ci.example.com/hooks/git.
- (Optional) For Secret, enter a random string. Without a secret, deliveries are not signed.
- Under Events, select the events to send. Pushes is selected to begin with.
- Leave Active selected.
- Choose Create webhook. The webhook is listed with its events, Active, and None yet under Last delivery.
dcloud git webhooks create 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
--url https://ci.example.com/hooks/git --events push --events pull_request \
--secret "$WEBHOOK_SECRET"POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/webhooks
{ "url": "https://ci.example.com/hooks/git", "events": ["push", "pull_request"], "secret": "EXAMPLE-SECRET" }resource "dcloud_git_webhook" "ci" {
repository_id = dcloud_git_repository.this.id
url = "https://ci.example.com/hooks/git"
events = ["push", "pull_request"]
secret = var.webhook_secret
}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.