# 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:CreateWebhook` on the repository. A repository holds a limited number of
  webhooks (quota `git.webhooks`; see [Quotas](quotas.md)).
- 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

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

**CLI**
```sh
dcloud git webhooks create 5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60 \
  --url https://ci.example.com/hooks/git --events push --events pull_request \
  --secret "$WEBHOOK_SECRET"
```

**API**
```http
POST /git/api/repositories/5d6c2a1e-7b3f-4c8d-9e0a-1b2c3d4e5f60/webhooks
{ "url": "https://ci.example.com/hooks/git", "events": ["push", "pull_request"], "secret": "EXAMPLE-SECRET" }
```

**Terraform**
```hcl
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](view-webhook-deliveries.md) to check what was sent and what came back.

## Related

- `git.webhooks.create` · `dcloud git webhooks create` · `dcloud_git_webhook`
