gitea/gitea-docs
1
0
Fork 0
mirror of https://gitea.com/gitea/docs.git synced 2026-06-11 04:31:26 +00:00
Code Issues Packages Projects Releases Wiki Activity

update webhook documentation (#393)

Browse Source 
Reviewed-on: https://gitea.com/gitea/docs/pulls/393
This commit is contained in:
Lunny Xiao
2026-05-01 16:40:27 +00:00
parent f550d33ad7
commit 14b76120b4
9 changed files with 6063 additions and 1227 deletions
Download Patch File Download Diff File Expand all files Collapse all files

816
docs/usage/repository/webhooks.md
View File

@@ -9,11 +9,26 @@ aliases:
# Webhooks
Gitea supports webhooks for repository events. This can be configured in the settings
page `/:username/:reponame/settings/hooks` by a repository admin. Webhooks can also be configured on a per-organization and whole system basis.
All event pushes are POST requests. The methods currently supported are:
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.
- Gitea (can also be a GET request)
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
@@ -21,170 +36,697 @@ All event pushes are POST requests. The methods currently supported are:
- Telegram
- Microsoft Teams
- Feishu
- Matrix
- Wechatwork
- Packagist
### Event information
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.
:::warning
The `secret` field in the payload is deprecated as of Gitea 1.13.0 and will be removed in 1.14.0: https://github.com/go-gitea/gitea/issues/11755
## 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.
:::note
Older examples may still show a `secret` field inside the JSON payload. Current
Gitea versions do not send the webhook secret in the payload body. Always verify
the request by checking the signature headers instead.
:::
The following is an example of event information that will be sent by Gitea to
a Payload URL:
### Branch filters
The branch filter uses glob syntax compatible with
[`github.com/gobwas/glob`](https://pkg.go.dev/github.com/gobwas/glob#Compile).
- 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](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization)
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.
| Header | Description |
| --- | --- |
| `X-Gitea-Delivery` | Unique delivery UUID for this attempt. |
| `X-Gitea-Event` | Normalized event name, such as `push`, `issues`, or `pull_request`. |
| `X-Gitea-Event-Type` | More specific event type, such as `issue_assign` or `pull_request_review_comment`. |
| `X-Gitea-Signature` | Hex-encoded HMAC-SHA256 of the raw request body, without a prefix. |
| `X-Gitea-Hook-Installation-Target-Type` | Where the webhook is defined: typically `repository`, `organization`, `user`, or `system`. Default webhooks are copied into repositories before delivery, so they are typically delivered as `repository`. |
| `X-Gogs-Delivery`, `X-Gogs-Event`, `X-Gogs-Event-Type`, `X-Gogs-Signature` | Compatibility headers with the same values as the Gitea variants. |
| `X-GitHub-Delivery`, `X-GitHub-Event`, `X-GitHub-Event-Type` | GitHub-style compatibility headers. |
| `X-GitHub-Hook-Installation-Target-Type` | GitHub-style compatibility header for the webhook scope. |
| `X-Hub-Signature` | GitHub-compatible HMAC-SHA1 header in the form `sha1=<digest>`. |
| `X-Hub-Signature-256` | GitHub-compatible HMAC-SHA256 header in the form `sha256=<digest>`. |
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:
```http
X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-GitHub-Event: push
X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gogs-Event: push
X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Gitea-Event: push
X-Gitea-Event: issues
X-Gitea-Event-Type: issue_assign
X-GitHub-Event: issues
X-GitHub-Event-Type: issue_assign
```
```json
{
"secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
"ref": "refs/heads/develop",
"before": "28e1879d029cb852e4844d9c718537df08844e03",
"after": "bffeb74224043ba2feb48d137756c8a9331c449a",
"compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
"commits": [
{
"id": "bffeb74224043ba2feb48d137756c8a9331c449a",
"message": "Webhooks Yay!",
"url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
"author": {
"name": "Gitea",
"email": "someone@gitea.io",
"username": "gitea"
},
"committer": {
"name": "Gitea",
"email": "someone@gitea.io",
"username": "gitea"
},
"timestamp": "2017-03-13T13:52:11-04:00"
}
],
"repository": {
"id": 140,
"owner": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
},
"name": "webhooks",
"full_name": "gitea/webhooks",
"description": "",
"private": false,
"fork": false,
"html_url": "http://localhost:3000/gitea/webhooks",
"ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
"clone_url": "http://localhost:3000/gitea/webhooks.git",
"website": "",
"stars_count": 0,
"forks_count": 1,
"watchers_count": 1,
"open_issues_count": 7,
"default_branch": "master",
"created_at": "2017-02-26T04:29:06-05:00",
"updated_at": "2017-03-13T13:51:58-04:00"
},
"pusher": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
},
"sender": {
"id": 1,
"login": "gitea",
"full_name": "Gitea",
"email": "someone@gitea.io",
"avatar_url": "https://localhost:3000/avatars/1",
"username": "gitea"
}
}
```
Use `X-Gitea-Event-Type` when you need the exact trigger that fired the webhook.
### Example
#### Validating deliveries
This is an example of how to use webhooks to run a php script upon push requests to the repository.
In your repository Settings, under Webhooks, Setup a Gitea webhook as follows:
Gitea signs the raw request body with your webhook secret. To validate a
delivery:
- Target URL: http://mydomain.com/webhook.php
- HTTP Method: POST
- POST Content Type: application/json
- Secret: 123
- Trigger On: Push Events
- Active: Checked
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.
Now on your server create the php file webhook.php
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
<?php
$secret_key = '123';
$secret = '123';
// check for POST request
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
exit();
if ($_SERVER['REQUEST_METHOD'] !== 'POST') {
http_response_code(405);
exit('Only POST is allowed');
}
// get content type
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
$payload = file_get_contents('php://input');
$signature = $_SERVER['HTTP_X_GITEA_SIGNATURE'] ?? '';
if ($content_type != 'application/json') {
error_log('FAILED - not application/json - '. $content_type);
exit();
if ($payload === false || $signature === '') {
http_response_code(400);
exit('Missing payload or signature');
}
// get payload
$payload = trim(file_get_contents("php://input"));
$expected = hash_hmac('sha256', $payload, $secret);
if (empty($payload)) {
error_log('FAILED - no payload');
exit();
if (!hash_equals($expected, $signature)) {
http_response_code(401);
exit('Invalid signature');
}
// get header signature
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
$event = $_SERVER['HTTP_X_GITEA_EVENT'] ?? '';
$eventType = $_SERVER['HTTP_X_GITEA_EVENT_TYPE'] ?? '';
$data = json_decode($payload, true);
if (empty($header_signature)) {
error_log('FAILED - header signature missing');
exit();
if (!is_array($data)) {
http_response_code(400);
exit('Invalid JSON payload');
}
// calculate payload signature
$payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
// check payload signature against header signature
if ($header_signature !== $payload_signature) {
error_log('FAILED - payload signature');
exit();
}
// convert json to array
$decoded = json_decode($payload, true);
// check for json decode errors
if (json_last_error() !== JSON_ERROR_NONE) {
error_log('FAILED - json decode - '. json_last_error());
exit();
}
// success, do something
http_response_code(204);
```
There is a Test Delivery button in the webhook settings that allows to test the configuration as well as a list of the most Recent Deliveries.
## Events
### Authorization header
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.
**With 1.19**, Gitea hooks can be configured to send an [authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) to the webhook target.
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
| Name | Type | Description |
| --- | --- | --- |
| `sha` | `string` | **Required.** The object ID of the created reference. |
| `ref` | `string` | **Required.** The created branch or tag name. |
| `ref_type` | `string` | **Required.** The reference type, such as `branch` or `tag`. |
| `repository` | `object` | **Required.** The repository where the reference was created. |
| `sender` | `object` | **Required.** The user who created the reference. |
#### `delete`
This event occurs when a branch or tag is deleted.
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `ref` | `string` | **Required.** The deleted branch or tag name. |
| `ref_type` | `string` | **Required.** The reference type, such as `branch` or `tag`. |
| `pusher_type` | `string` | **Required.** The actor type that deleted the ref. Current Gitea payloads use `user`. |
| `repository` | `object` | **Required.** The repository where the reference was deleted. |
| `sender` | `object` | **Required.** The user who deleted the reference. |
#### `fork`
This event occurs when a repository is forked.
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `forkee` | `object` | **Required.** The newly created fork repository. |
| `repository` | `object` | **Required.** The original repository that was forked. |
| `sender` | `object` | **Required.** The user who created the fork. |
#### `push`
This event occurs when commits are pushed to a branch or tag.
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `ref` | `string` | **Required.** The full pushed ref, such as `refs/heads/main`. |
| `before` | `string` | **Required.** The commit SHA before the push. |
| `after` | `string` | **Required.** The commit SHA after the push. |
| `compare_url` | `string` | **Required.** URL to compare `before` and `after`. |
| `commits` | `array` | **Required.** Commits included in the push. |
| `total_commits` | `integer` | **Required.** Number of commits in the push. |
| `head_commit` | `object` | The most recent commit in the push. |
| `repository` | `object` | **Required.** The repository that received the push. |
| `pusher` | `object` | **Required.** The user who performed the push. |
| `sender` | `object` | **Required.** The user who triggered the webhook. |
#### `wiki`
This event occurs when a wiki page is created, edited, or deleted.
**Action type:** `created`, `edited`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The wiki page action. |
| `repository` | `object` | **Required.** The repository that owns the wiki. |
| `sender` | `object` | **Required.** The user who changed the wiki page. |
| `page` | `string` | **Required.** The wiki page name. |
| `comment` | `string` | The wiki commit message or comment. |
#### `repository`
This event occurs when a repository is created or deleted.
**Action type:** `created`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The repository action. |
| `repository` | `object` | **Required.** The repository that was created or deleted. |
| `organization` | `object` | Present when the repository belongs to an organization. |
| `sender` | `object` | **Required.** The user who performed the action. |
#### `release`
This event occurs when a release is published, updated, or deleted.
**Action type:** `published`, `updated`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The release action. |
| `release` | `object` | **Required.** The release that was acted on. |
| `repository` | `object` | **Required.** The repository containing the release. |
| `sender` | `object` | **Required.** The user who performed the action. |
#### `package`
This event occurs when a package is created or deleted.
**Action type:** `created`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The package action. |
| `repository` | `object` | The repository associated with the package, when applicable. |
| `package` | `object` | **Required.** The package that was acted on. |
| `organization` | `object` | Present when the package owner is an organization. |
| `sender` | `object` | **Required.** The user who performed the action. |
#### `status`
This event occurs when a commit status is created or updated through the API.
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `commit` | `object` | The commit associated with the status. |
| `context` | `string` | **Required.** The status context, such as `ci/build`. |
| `created_at` | `string` | **Required.** The time the status was created. |
| `description` | `string` | Status description text. |
| `id` | `integer` | **Required.** The status identifier. |
| `repository` | `object` | **Required.** The repository containing the commit. |
| `sender` | `object` | **Required.** The user who created the status. |
| `sha` | `string` | **Required.** The commit SHA. |
| `state` | `string` | **Required.** The state, such as `pending`, `success`, `error`, or `failure`. |
| `target_url` | `string` | Target URL associated with the status. |
| `updated_at` | `string` | The time the status was last updated. |
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
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The issue action. |
| `number` | `integer` | **Required.** The issue number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `issue` | `object` | **Required.** The issue that was acted on. |
| `repository` | `object` | **Required.** The repository containing the issue. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
#### `issue_assign`
This event occurs when an issue is assigned or unassigned.
**Action type:** `assigned`, `unassigned`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The assignment action. |
| `number` | `integer` | **Required.** The issue number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `issue` | `object` | **Required.** The issue that was acted on. |
| `repository` | `object` | **Required.** The repository containing the issue. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
#### `issue_label`
This event occurs when issue labels are updated or cleared.
**Action type:** `label_updated`, `label_cleared`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The label update action. |
| `number` | `integer` | **Required.** The issue number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `issue` | `object` | **Required.** The issue that was acted on. |
| `repository` | `object` | **Required.** The repository containing the issue. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
#### `issue_milestone`
This event occurs when an issue is milestoned or demilestoned.
**Action type:** `milestoned`, `demilestoned`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The milestone action. |
| `number` | `integer` | **Required.** The issue number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `issue` | `object` | **Required.** The issue that was acted on. |
| `repository` | `object` | **Required.** The repository containing the issue. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the issue action, if applicable. |
#### `issue_comment`
This event occurs when a comment on an issue is created, edited, or deleted.
**Action type:** `created`, `edited`, `deleted`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The comment action. |
| `issue` | `object` | **Required.** The issue that the comment belongs to. |
| `pull_request` | `object` | Present only when the comment is on a pull request timeline. |
| `comment` | `object` | **Required.** The comment that was created, edited, or deleted. |
| `changes` | `object` | Optional. Previous comment body when the action is `edited`. |
| `repository` | `object` | **Required.** The repository containing the issue. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `is_pull` | `boolean` | **Required.** Whether the comment is on a pull request timeline. |
### 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
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The pull request action. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was acted on. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
| `review` | `object` | Present for pull request review events. |
#### `pull_request_assign`
This event occurs when a pull request is assigned or unassigned.
**Action type:** `assigned`, `unassigned`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The assignment action. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was acted on. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
| `review` | `object` | Present for pull request review events. |
#### `pull_request_label`
This event occurs when pull request labels are updated or cleared.
**Action type:** `label_updated`, `label_cleared`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The label update action. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was acted on. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
| `review` | `object` | Present for pull request review events. |
#### `pull_request_milestone`
This event occurs when a pull request is milestoned or demilestoned.
**Action type:** `milestoned`, `demilestoned`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The milestone action. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was acted on. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
| `review` | `object` | Present for pull request review events. |
#### `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
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The comment action. |
| `issue` | `object` | **Required.** The related issue record for the pull request. |
| `pull_request` | `object` | **Required.** The pull request the timeline comment belongs to. |
| `comment` | `object` | **Required.** The comment that was created, edited, or deleted. |
| `changes` | `object` | Optional. Previous comment body when the action is `edited`. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `is_pull` | `boolean` | **Required.** Always `true` for this event. |
#### `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
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** Always `reviewed`. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was reviewed. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who submitted the review. |
| `commit_id` | `string` | The commit SHA associated with the review event, if applicable. |
| `review` | `object` | **Required.** The review payload. For this event, `review.type` is `approved`. |
#### `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
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** Always `reviewed`. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was reviewed. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who submitted the review. |
| `commit_id` | `string` | The commit SHA associated with the review event, if applicable. |
| `review` | `object` | **Required.** The review payload. For this event, `review.type` is `rejected`. |
#### `pull_request_review_comment`
This event occurs when a pull request review is submitted as a comment.
**Action type:** `reviewed`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** Always `reviewed`. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was reviewed. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who submitted the review. |
| `commit_id` | `string` | The commit SHA associated with the review event, if applicable. |
| `review` | `object` | **Required.** The review payload. For this event, `review.type` is `comment`. |
#### `pull_request_sync`
This event occurs when a pull request is synchronized after new commits are pushed.
**Action type:** `synchronized`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** Always `synchronized`. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was synchronized. |
| `requested_reviewer` | `object` | Present for review request events. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the synchronization. |
| `commit_id` | `string` | The commit SHA associated with the synchronization event, if applicable. |
| `review` | `object` | Present for pull request review events. |
#### `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
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The review request action. |
| `number` | `integer` | **Required.** The pull request number. |
| `changes` | `object` | Optional. Previous values for edited fields or label deltas. |
| `pull_request` | `object` | **Required.** The pull request that was acted on. |
| `requested_reviewer` | `object` | The reviewer that was requested or removed. |
| `repository` | `object` | **Required.** The repository containing the pull request. |
| `sender` | `object` | **Required.** The user who performed the action. |
| `commit_id` | `string` | The commit SHA associated with the pull request action, if applicable. |
| `review` | `object` | Present for pull request review events. |
### 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
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The workflow run status transition. |
| `workflow` | `object` | **Required.** The workflow definition. |
| `workflow_run` | `object` | **Required.** The workflow run that was acted on. |
| `pull_request` | `object` | Present when the workflow run is associated with a pull request. |
| `organization` | `object` | Present when the repository owner is an organization. |
| `repository` | `object` | **Required.** The repository containing the workflow. |
| `sender` | `object` | **Required.** The user who triggered the workflow run update. |
#### `workflow_job`
This event occurs when a Gitea Actions workflow job changes status.
**Action type:** `queued`, `waiting`, `in_progress`, `completed`
##### Payload parameters
| Name | Type | Description |
| --- | --- | --- |
| `action` | `string` | **Required.** The workflow job status transition. |
| `workflow_job` | `object` | **Required.** The workflow job that was acted on. |
| `pull_request` | `object` | Present when the workflow job is associated with a pull request. |
| `organization` | `object` | Present when the repository owner is an organization. |
| `repository` | `object` | **Required.** The repository containing the workflow job. |
| `sender` | `object` | **Required.** The user who triggered the workflow job update. |
## 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](../../administration/config-cheat-sheet.md#webhook-webhook).