# Webhooks

A webhook posts an HTTP request to a URL you choose when something happens in a repository: a push, a pull request, a new issue, a release. Use it to trigger a deploy, notify a chat channel, or feed your own automation. If you want to react to deploy status from a hosting provider instead, see [deployment environments](/docs/environments/).

Webhooks are stock Forgejo. This page covers the Codebahn path to add and verify one. For the field-by-field payload schema of every event, see the [upstream webhooks reference](https://forgejo.org/docs/latest/user/webhooks/).

## Add a webhook

Go to your repository's **Settings > Webhooks** and add one. You set:

- **Target URL.** Where the request goes. Use HTTPS so the payload and signature stay encrypted in transit.
- **Content type.** `application/json` or `application/x-www-form-urlencoded`.
- **Secret.** A shared string used to sign each delivery. Leave it empty to skip signing, but signing is how your endpoint confirms a request came from Codebahn. See [Verify deliveries](#verify-deliveries).
- **Events.** Send everything, or pick from push, pull request, issues, releases, comments, branch creation and deletion, and more. The full list is on the settings page.

Save, then use **Test Delivery** to send a sample payload. Recent deliveries, with request and response bodies, are listed on the same page for debugging.

## Verify deliveries

If you set a secret, Codebahn computes an HMAC of the request body with that secret and sends it in a signature header. Your endpoint recomputes the HMAC over the raw body with the same secret and compares the two.

The signature arrives as HMAC-SHA256 in the `X-Hub-Signature-256` header (prefixed `sha256=...`) for GitHub-compatible consumers. The native `X-Forgejo-Signature` header carries the same HMAC as raw hex (no prefix). Verify against whichever your library supports, and use a constant-time comparison rather than plain string equality to avoid leaking timing information.

The [upstream webhooks reference](https://forgejo.org/docs/latest/user/webhooks/) includes a worked verification example.