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 also be a GET request)
  • Gogs
  • Slack
  • Discord
  • Dingtalk
  • Telegram
  • Microsoft Teams
  • Feishu
  • Wechatwork
  • Packagist

Event information

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

The following is an example of event information that will be sent by Gitea to a Payload URL:

  1. X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
  2. X-GitHub-Event: push
  3. X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
  4. X-Gogs-Event: push
  5. X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
  6. X-Gitea-Event: push
  1. {
  2.   "secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
  3.   "ref": "refs/heads/develop",
  4.   "before": "28e1879d029cb852e4844d9c718537df08844e03",
  5.   "after": "bffeb74224043ba2feb48d137756c8a9331c449a",
  6.   "compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
  7.   "commits": [
  8.     {
  9.       "id": "bffeb74224043ba2feb48d137756c8a9331c449a",
  10.       "message": "Webhooks Yay!",
  11.       "url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
  12.       "author": {
  13.         "name": "Gitea",
  14.         "email": "someone@gitea.io",
  15.         "username": "gitea"
  16.       },
  17.       "committer": {
  18.         "name": "Gitea",
  19.         "email": "someone@gitea.io",
  20.         "username": "gitea"
  21.       },
  22.       "timestamp": "2017-03-13T13:52:11-04:00"
  23.     }
  24.   ],
  25.   "repository": {
  26.     "id": 140,
  27.     "owner": {
  28.       "id": 1,
  29.       "login": "gitea",
  30.       "full_name": "Gitea",
  31.       "email": "someone@gitea.io",
  32.       "avatar_url": "https://localhost:3000/avatars/1",
  33.       "username": "gitea"
  34.     },
  35.     "name": "webhooks",
  36.     "full_name": "gitea/webhooks",
  37.     "description": "",
  38.     "private": false,
  39.     "fork": false,
  40.     "html_url": "http://localhost:3000/gitea/webhooks",
  41.     "ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
  42.     "clone_url": "http://localhost:3000/gitea/webhooks.git",
  43.     "website": "",
  44.     "stars_count": 0,
  45.     "forks_count": 1,
  46.     "watchers_count": 1,
  47.     "open_issues_count": 7,
  48.     "default_branch": "master",
  49.     "created_at": "2017-02-26T04:29:06-05:00",
  50.     "updated_at": "2017-03-13T13:51:58-04:00"
  51.   },
  52.   "pusher": {
  53.     "id": 1,
  54.     "login": "gitea",
  55.     "full_name": "Gitea",
  56.     "email": "someone@gitea.io",
  57.     "avatar_url": "https://localhost:3000/avatars/1",
  58.     "username": "gitea"
  59.   },
  60.   "sender": {
  61.     "id": 1,
  62.     "login": "gitea",
  63.     "full_name": "Gitea",
  64.     "email": "someone@gitea.io",
  65.     "avatar_url": "https://localhost:3000/avatars/1",
  66.     "username": "gitea"
  67.   }
  68. }

Example

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:

Now on your server create the php file webhook.php

  1. <?php
  3. $secret_key = '123';
  5. // check for POST request
  6. if ($_SERVER['REQUEST_METHOD'] != 'POST') {
  7.     error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
  8.     exit();
  9. }
  11. // get content type
  12. $content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
  14. if ($content_type != 'application/json') {
  15.     error_log('FAILED - not application/json - '. $content_type);
  16.     exit();
  17. }
  19. // get payload
  20. $payload = trim(file_get_contents("php://input"));
  22. if (empty($payload)) {
  23.     error_log('FAILED - no payload');
  24.     exit();
  25. }
  27. // get header signature
  28. $header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
  30. if (empty($header_signature)) {
  31.     error_log('FAILED - header signature missing');
  32.     exit();
  33. }
  35. // calculate payload signature
  36. $payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
  38. // check payload signature against header signature
  39. if ($header_signature !== $payload_signature) {
  40.     error_log('FAILED - payload signature');
  41.     exit();
  42. }
  44. // convert json to array
  45. $decoded = json_decode($payload, true);
  47. // check for json decode errors
  48. if (json_last_error() !== JSON_ERROR_NONE) {
  49.     error_log('FAILED - json decode - '. json_last_error());
  50.     exit();
  51. }
  53. // success, do something

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.

Authorization header

With 1.19, Gitea hooks can be configured to send an authorization header to the webhook target.