Webhooks

Gitea 可以為儲存庫活動送出對外 Webhook。儲存庫層級的 Webhook 由儲存庫管理員 在 /:username/:reponame/settings/hooks 中設定。組織、使用者與系統管理層級 也有對應的 Webhook 設定頁面。

Webhook 設定支援四種範圍：

• 儲存庫 Webhook：只會對單一儲存庫中的活動觸發。
• 組織 Webhook：對該組織擁有的儲存庫中的活動觸發。
• 使用者 Webhook：對該使用者擁有的儲存庫中的活動觸發。
• 系統 Webhook：對實例中所有符合條件的活動觸發。

Gitea 也支援由管理員定義的 預設 Webhook。它並不是額外的投遞範圍，而是會在 建立新儲存庫時被複製到該儲存庫中，之後就會像一般儲存庫 Webhook 一樣運作。

Gitea 支援以下對外 Webhook 整合：

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

Gitea 與 Gogs 類型會送出通用 Webhook payload。上面列出的聊天與服務整合 則會把同一個內部事件轉換成各自服務所需的請求主體格式。

本頁分成三個部分：

• 設定：如何設定 Webhook 選項，例如 URL、密鑰、分支過濾器與授權標頭。
• 投遞：Gitea 如何送出 Webhook 請求、會附帶哪些標頭，以及如何驗證投遞。
• 事件：Gitea 會投遞哪些事件，以及每個事件包含哪些頂層 payload 參數。

設定​

本節介紹在建立或編輯 Webhook 時可以設定的選項。

設定 Webhook​

建立 Webhook 時，主要設定項目包括：

• Target URL：接收投遞的目標位址。
• HTTP Method：通用 Webhook 通常使用 POST。
• POST Content Type：通用 Webhook 可使用 application/json 或 application/x-www-form-urlencoded。
• Secret：用來對原始請求主體進行 HMAC 簽章。
• Authorization Header：可選的自訂 Authorization 標頭，會隨每次請求送出。
• Branch Filter：可選的分支或標籤過濾規則。
• Trigger On：Push Events、All Events 或自訂事件選擇。
• Active：是否啟用該 Webhook。

分支過濾器​

分支過濾器使用與 github.com/gobwas/glob 相容的 glob 語法。

• 空值、* 或 ** 代表符合全部。
• 像 main 這樣的一般分支名稱會符合該分支。
• 也支援 refs/tags/v* 這類完整 ref。
• 支援 {main,release/*} 這類大括號表達式。
• 過濾器只會套用在帶有 git ref 的事件，例如 create、delete 與 push。
• 不帶 ref 的事件，例如 issue 或 release，會忽略分支過濾器。

範例：

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

授權標頭​

Gitea 可以設定為在每次 Webhook 投遞時送出自訂的 Authorization header。 它與 Webhook 密鑰彼此獨立：

• 使用密鑰透過 HMAC 驗證請求完整性。
• 當接收端需要應用層認證時，使用 Authorization 標頭。

投遞​

本節說明 Gitea 如何送出 Webhook 投遞，以及接收端如何識別與驗證這些請求。

投遞行為​

• Webhook 會透過 HTTP 非同步投遞。
• 通用 Gitea 與 Gogs Webhook 支援 POST 與 GET；通常應使用 POST。
• 對於 POST 請求，payload 可以直接以 JSON （application/json）送出，也可以放在名為 payload 的表單欄位中 （application/x-www-form-urlencoded）。
• 某些特定服務整合可能會使用該服務要求的 HTTP 方法與請求主體格式。

投遞標頭​

每次投遞都包含唯一的 delivery ID 與事件標頭。對於相容 GitHub 的整合， Gitea 也會同時送出對應的 GitHub 與 Gogs 風格標頭。

如果未設定密鑰，簽章標頭仍然會存在，但摘要值為空。

Event 與 Event-Type​

某些 Gitea Webhook 訂閱會被歸類到同一個規範化事件名稱下。例如，issue 指派 投遞會歸類到 issue 事件群組：

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

如果你需要知道實際觸發投遞的具體事件類型，請使用 X-Gitea-Event-Type。

驗證投遞​

Gitea 會使用你的 Webhook 密鑰對原始請求主體進行簽章。要驗證一次投遞：

1. 以接收到的原始內容讀取請求主體。
2. 使用 Webhook 密鑰計算 HMAC-SHA256 摘要。
3. 將結果與 X-Gitea-Signature 或 GitHub 相容的 X-Hub-Signature-256 進行比較。
4. 盡量使用常數時間比較函式。

注意事項：

• X-Gitea-Signature 只包含小寫十六進位的 SHA-256 摘要。
• X-Hub-Signature-256 使用相同摘要，但帶有 sha256= 前綴。
• X-Hub-Signature 也會為了相容性而送出，其演算法為 SHA-1。
• 在完成簽章驗證之前，不應先解析 JSON 或修改請求主體。

PHP 範例​

下面的範例示範如何驗證以 application/json 送出的通用 Gitea Webhook。

<?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);

事件​

本節採用與 GitHub Webhook 文件類似的逐事件描述方式：每個事件都會說明 觸發時機，以及 payload 中包含哪些頂層欄位。

事件分組與 Webhook 設定介面中的分組一致：Repository Events、 Issue Events、Pull Request Events 與 Workflow Events。

儲存庫事件​

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

create​

當分支或標籤被建立時，會觸發此事件。

Payload 參數​

delete​

當分支或標籤被刪除時，會觸發此事件。

Payload 參數​

fork​

當儲存庫被 fork 時，會觸發此事件。

Payload 參數​

push​

當提交被推送到某個分支或標籤時，會觸發此事件。

Payload 參數​

wiki​

當 Wiki 頁面被建立、編輯或刪除時，會觸發此事件。

動作類型： created、edited、deleted

Payload 參數​

repository​

當儲存庫被建立或刪除時，會觸發此事件。

動作類型： created、deleted

Payload 參數​

release​

當發行版本被發佈、更新或刪除時，會觸發此事件。

動作類型： published、updated、deleted

Payload 參數​

package​

當套件被建立或刪除時，會觸發此事件。

動作類型： created、deleted

Payload 參數​

status​

當透過 API 建立或更新提交狀態時，會觸發此事件。

Payload 參數​

與多數其他 payload 不同，此事件不使用 action 欄位，狀態變化透過 state 欄位表示。

議題事件​

• issues、issue_assign、issue_label、issue_milestone、issue_comment

issues​

當 issue 被開啟、關閉、重新開啟、編輯或刪除時，會觸發此事件。

動作類型： opened、closed、reopened、edited、deleted

Payload 參數​

issue_assign​

當 issue 被指派或取消指派時，會觸發此事件。

動作類型： assigned、unassigned

Payload 參數​

issue_label​

當 issue 標籤被更新或清空時，會觸發此事件。

動作類型： label_updated、label_cleared

Payload 參數​

issue_milestone​

當 issue 被設定里程碑或移除里程碑時，會觸發此事件。

動作類型： milestoned、demilestoned

Payload 參數​

issue_comment​

當 issue 評論被建立、編輯或刪除時，會觸發此事件。

動作類型： created、edited、deleted

Payload 參數​

Pull Request 事件​

• 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​

當 pull request 被開啟、關閉、重新開啟、編輯或刪除時，會觸發此事件。

動作類型： opened、closed、reopened、edited、deleted

Payload 參數​

pull_request_assign​

當 pull request 被指派或取消指派時，會觸發此事件。

動作類型： assigned、unassigned

Payload 參數​

pull_request_label​

當 pull request 標籤被更新或清空時，會觸發此事件。

動作類型： label_updated、label_cleared

Payload 參數​

pull_request_milestone​

當 pull request 被設定里程碑或移除里程碑時，會觸發此事件。

動作類型： milestoned、demilestoned

Payload 參數​

pull_request_comment​

當 pull request 時間線評論被建立、編輯或刪除時，會觸發此事件。

動作類型： created、edited、deleted

Payload 參數​

pull_request_review​

這是 Webhook 設定介面中的一個僅用於訂閱的彙總事件。

它不會產生獨立的投遞 payload。勾選後，Gitea 實際投遞的是更具體的 pull_request_review_approved、pull_request_review_rejected 與 pull_request_review_comment 事件。

pull_request_review_approved​

當 pull request review 以核准形式提交時，會觸發此事件。

動作類型： reviewed

Payload 參數​

pull_request_review_rejected​

當 pull request review 以拒絕或請求修改的形式提交時，會觸發此事件。

動作類型： reviewed

Payload 參數​

pull_request_review_comment​

當 pull request review 以評論形式提交時，會觸發此事件。

動作類型： reviewed

Payload 參數​

pull_request_sync​

當新的提交被推送後，pull request 被同步時，會觸發此事件。

動作類型： synchronized

Payload 參數​

pull_request_review_request​

當請求審查者或移除審查請求時，會觸發此事件。

動作類型： review_requested、review_request_removed

Payload 參數​

工作流程事件​

• workflow_run、workflow_job

workflow_run​

當 Gitea Actions 工作流程執行狀態發生變化時，會觸發此事件。

動作類型： queued、waiting、in_progress、completed

Payload 參數​

workflow_job​

當 Gitea Actions 工作流程作業狀態發生變化時，會觸發此事件。

動作類型： queued、waiting、in_progress、completed

Payload 參數​

測試、最近投遞與重新投遞​

每個 Webhook 頁面都包含：

• Test Delivery：會向儲存庫送出一次模擬的 push 事件。
• Recent Deliveries：顯示請求與回應詳細資訊。
• Redelivery：重新投遞一筆歷史 Webhook 記錄。

如果儲存庫還沒有任何提交，測試投遞會使用一個產生的假提交，以便仍能測試 Webhook。

管理說明​

管理員還可以透過實例層級設定控制 Webhook 投遞，例如主機允許清單、投遞逾時 與清理策略。詳見 設定速查表中的 Webhook 小節。