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.

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.

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.
• 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 for GitHub-compatible consumers. The native X-Forgejo-Signature header carries the same value. 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 includes a worked verification example.