Webhooks

Gitea can send outbound webhooks for repository activity. Repository webhooks are configured at /:username/:reponame/settings/hooks by a repository admin. Equivalent webhook pages also exist for organizations, users, and system administration.

Webhook configuration is available at four scopes:

• Repository webhooks: Trigger only for activity in one repository.
• Organization webhooks: Trigger for activity in repositories owned by that organization.
• User webhooks: Trigger for activity in repositories owned by that user.
• System webhooks: Trigger for all eligible activity on the instance.

Gitea also supports admin-defined default webhooks. These are not an extra delivery scope. Instead, they are copied into newly created repositories and then behave like ordinary repository webhooks.

Gitea supports these outgoing webhook integrations:

• Gitea
• Gogs
• Slack
• Discord
• Dingtalk
• Telegram
• Microsoft Teams
• Feishu
• Matrix
• Wechatwork
• Packagist

The Gitea and Gogs webhook types send generic webhook payloads. The chat and service integrations listed above transform the same internal event into a service-specific request body.

Configuration​

This section covers the webhook settings you choose when creating or editing a webhook.

Configuring a webhook​

When creating a webhook, the main options are:

• Target URL: The endpoint that receives the delivery.
• HTTP Method: Usually POST for generic webhooks.
• POST Content Type: application/json or application/x-www-form-urlencoded for generic webhooks.
• Secret: Used to sign the raw request body with HMAC.
• Authorization Header: Optional custom Authorization header to send with each request.
• Branch Filter: Optional glob filter for branch and tag related events.
• Trigger On: Push Events, All Events, or a custom event selection.
• Active: Whether the webhook is enabled.

Branch filters​

The branch filter uses glob syntax compatible with github.com/gobwas/glob.

• Empty, *, or ** matches everything.
• A plain branch name such as main matches that branch.
• Full refs such as refs/tags/v* are also supported.
• Brace expressions such as {main,release/*} are supported.
• The filter only applies to events that carry a git ref, such as create, delete, and push.
• Events without a ref, such as issues or releases, ignore the branch filter.

Examples:

• main
• {main,feature/*}
• {refs/heads/feature/*,refs/tags/release/*}

Authorization header​

Gitea can be configured to send a custom Authorization header with each webhook delivery. This is independent from the webhook secret:

• Use the secret to verify integrity with HMAC.
• Use the Authorization header when the receiving endpoint requires application-level authentication.

Delivery​

This section describes how Gitea sends webhook deliveries and how receivers can identify and verify them.

Delivery behavior​

• Webhooks are delivered asynchronously over HTTP.
• Generic Gitea and Gogs webhooks support POST and GET; POST is the normal choice.
• For POST requests, the payload can be sent either as JSON (application/json) or as a form field named payload (application/x-www-form-urlencoded).
• Provider-specific integrations may use the HTTP method and body format required by that provider.

Delivery headers​

Every delivery includes a unique delivery ID and event headers. For GitHub-compatible integrations, Gitea also sends the corresponding GitHub and Gogs header names.

If no secret is configured, the signature headers are still present, but their digest values are empty.

Event versus Event-Type​

Some Gitea webhook subscriptions are grouped together under one normalized event name. For example, an issue assignment delivery uses the issue event group:

X-Gitea-Event: issues
X-Gitea-Event-Type: issue_assign
X-GitHub-Event: issues
X-GitHub-Event-Type: issue_assign

Use X-Gitea-Event-Type when you need the exact trigger that fired the webhook.

Validating deliveries​

Gitea signs the raw request body with your webhook secret. To validate a delivery:

1. Read the request body exactly as it was received.
2. Compute the HMAC-SHA256 digest with your webhook secret.
3. Compare the result with X-Gitea-Signature or with the GitHub-compatible X-Hub-Signature-256 header.
4. Use a constant-time comparison when possible.

Important details:

• X-Gitea-Signature contains only the lowercase hexadecimal SHA-256 digest.
• X-Hub-Signature-256 contains the same digest with a sha256= prefix.
• X-Hub-Signature is also sent for compatibility and uses SHA-1.
• The body must be verified before JSON parsing or any other modification.

PHP example​

The following example verifies a generic Gitea webhook sent as application/json.

<?php

$secret = '123';

if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
    http_response_code(405);
    exit('Only POST is allowed');
}

$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';

if ($payload === false || $signature === '') {
    http_response_code(400);
    exit('Missing payload or signature');
}

$expected = hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit('Invalid signature');
}

$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
$data = json_decode($payload, true);

if (!is_array($data)) {
    http_response_code(400);
    exit('Invalid JSON payload');
}

http_response_code(204);

Events​

This section follows the same event-by-event style used by GitHub's webhook documentation: each event describes when it occurs and what the top-level payload contains.

The event groups match the webhook settings UI: Repository Events, Issue Events, Pull Request Events, and Workflow Events.

Repository Events​

• create, delete, fork, push, wiki, repository, release, package, status

create​

This event occurs when a branch or tag is created.

Payload parameters​

delete​

This event occurs when a branch or tag is deleted.

Payload parameters​

fork​

This event occurs when a repository is forked.

Payload parameters​

push​

This event occurs when commits are pushed to a branch or tag.

Payload parameters​

wiki​

This event occurs when a wiki page is created, edited, or deleted.

Action type: created, edited, deleted

Payload parameters​

repository​

This event occurs when a repository is created or deleted.

Action type: created, deleted

Payload parameters​

release​

This event occurs when a release is published, updated, or deleted.

Action type: published, updated, deleted

Payload parameters​

package​

This event occurs when a package is created or deleted.

Action type: created, deleted

Payload parameters​

status​

This event occurs when a commit status is created or updated through the API.

Payload parameters​

Unlike most other payloads, this event does not use an action field. The state transition is represented by state.

Issue Events​

• issues, issue_assign, issue_label, issue_milestone, issue_comment

issues​

This event occurs when an issue is opened, closed, reopened, edited, or deleted.

Action type: opened, closed, reopened, edited, deleted

Payload parameters​

issue_assign​

This event occurs when an issue is assigned or unassigned.

Action type: assigned, unassigned

Payload parameters​

issue_label​

This event occurs when issue labels are updated or cleared.

Action type: label_updated, label_cleared

Payload parameters​

issue_milestone​

This event occurs when an issue is milestoned or demilestoned.

Action type: milestoned, demilestoned

Payload parameters​

issue_comment​

This event occurs when a comment on an issue is created, edited, or deleted.

Action type: created, edited, deleted

Payload parameters​

Pull Request Events​

• pull_request, pull_request_assign, pull_request_label, pull_request_milestone, pull_request_comment, pull_request_review, pull_request_review_approved, pull_request_review_rejected, pull_request_review_comment, pull_request_sync, pull_request_review_request

pull_request​

This event occurs when a pull request is opened, closed, reopened, edited, or deleted.

Action type: opened, closed, reopened, edited, deleted

Payload parameters​

pull_request_assign​

This event occurs when a pull request is assigned or unassigned.

Action type: assigned, unassigned

Payload parameters​

pull_request_label​

This event occurs when pull request labels are updated or cleared.

Action type: label_updated, label_cleared

Payload parameters​

pull_request_milestone​

This event occurs when a pull request is milestoned or demilestoned.

Action type: milestoned, demilestoned

Payload parameters​

pull_request_comment​

This event occurs when a timeline comment on a pull request is created, edited, or deleted.

Action type: created, edited, deleted

Payload parameters​

pull_request_review​

This is a subscription-only umbrella event in the webhook settings UI.

It does not have its own delivery payload. When selected, Gitea delivers the more specific events pull_request_review_approved, pull_request_review_rejected, and pull_request_review_comment.

pull_request_review_approved​

This event occurs when a pull request review is submitted with approval.

Action type: reviewed

Payload parameters​

pull_request_review_rejected​

This event occurs when a pull request review is submitted with a rejection or a request for changes.

Action type: reviewed

Payload parameters​

pull_request_review_comment​

This event occurs when a pull request review is submitted as a comment.

Action type: reviewed

Payload parameters​

pull_request_sync​

This event occurs when a pull request is synchronized after new commits are pushed.

Action type: synchronized

Payload parameters​

pull_request_review_request​

This event occurs when a reviewer is requested or a review request is removed.

Action type: review_requested, review_request_removed

Payload parameters​

Workflow Events​

• workflow_run, workflow_job

workflow_run​

This event occurs when a Gitea Actions workflow run changes status.

Action type: queued, waiting, in_progress, completed

Payload parameters​

workflow_job​

This event occurs when a Gitea Actions workflow job changes status.

Action type: queued, waiting, in_progress, completed

Payload parameters​

Testing, recent deliveries, and replay​

Each webhook page includes:

• Test Delivery, which sends a synthetic push event for the repository.
• Recent Deliveries, which shows request and response details.
• Redelivery, which replays an earlier webhook delivery.

If the repository has no commits yet, the test delivery uses a generated fake commit so the webhook can still be exercised.

Administration notes​

Administrators can further control webhook delivery with instance settings such as host allow lists, delivery timeouts, and cleanup policies. See the Webhook section of the configuration cheat sheet.