code.gitea.io/gitea@v1.22.3/docs/content/usage/webhooks.en-us.md (about)

     1  ---
     2  date: "2016-12-01T16:00:00+02:00"
     3  title: "Webhooks"
     4  slug: "webhooks"
     5  sidebar_position: 30
     6  toc: false
     7  draft: false
     8  aliases:
     9    - /en-us/webhooks
    10  menu:
    11    sidebar:
    12      parent: "usage"
    13      name: "Webhooks"
    14      sidebar_position: 30
    15      identifier: "webhooks"
    16  ---
    17  
    18  # Webhooks
    19  
    20  Gitea supports webhooks for repository events. This can be configured in the settings
    21  page `/:username/:reponame/settings/hooks` by a repository admin. Webhooks can also be configured on a per-organization and whole system basis.
    22  All event pushes are POST requests. The methods currently supported are:
    23  
    24  - Gitea (can also be a GET request)
    25  - Gogs
    26  - Slack
    27  - Discord
    28  - Dingtalk
    29  - Telegram
    30  - Microsoft Teams
    31  - Feishu
    32  - Wechatwork
    33  - Packagist
    34  
    35  ### Event information
    36  
    37  **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
    38  
    39  The following is an example of event information that will be sent by Gitea to
    40  a Payload URL:
    41  
    42  ```
    43  X-GitHub-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
    44  X-GitHub-Event: push
    45  X-Gogs-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
    46  X-Gogs-Event: push
    47  X-Gitea-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
    48  X-Gitea-Event: push
    49  ```
    50  
    51  ```json
    52  {
    53    "secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
    54    "ref": "refs/heads/develop",
    55    "before": "28e1879d029cb852e4844d9c718537df08844e03",
    56    "after": "bffeb74224043ba2feb48d137756c8a9331c449a",
    57    "compare_url": "http://localhost:3000/gitea/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
    58    "commits": [
    59      {
    60        "id": "bffeb74224043ba2feb48d137756c8a9331c449a",
    61        "message": "Webhooks Yay!",
    62        "url": "http://localhost:3000/gitea/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
    63        "author": {
    64          "name": "Gitea",
    65          "email": "someone@gitea.io",
    66          "username": "gitea"
    67        },
    68        "committer": {
    69          "name": "Gitea",
    70          "email": "someone@gitea.io",
    71          "username": "gitea"
    72        },
    73        "timestamp": "2017-03-13T13:52:11-04:00"
    74      }
    75    ],
    76    "repository": {
    77      "id": 140,
    78      "owner": {
    79        "id": 1,
    80        "login": "gitea",
    81        "full_name": "Gitea",
    82        "email": "someone@gitea.io",
    83        "avatar_url": "https://localhost:3000/avatars/1",
    84        "username": "gitea"
    85      },
    86      "name": "webhooks",
    87      "full_name": "gitea/webhooks",
    88      "description": "",
    89      "private": false,
    90      "fork": false,
    91      "html_url": "http://localhost:3000/gitea/webhooks",
    92      "ssh_url": "ssh://gitea@localhost:2222/gitea/webhooks.git",
    93      "clone_url": "http://localhost:3000/gitea/webhooks.git",
    94      "website": "",
    95      "stars_count": 0,
    96      "forks_count": 1,
    97      "watchers_count": 1,
    98      "open_issues_count": 7,
    99      "default_branch": "master",
   100      "created_at": "2017-02-26T04:29:06-05:00",
   101      "updated_at": "2017-03-13T13:51:58-04:00"
   102    },
   103    "pusher": {
   104      "id": 1,
   105      "login": "gitea",
   106      "full_name": "Gitea",
   107      "email": "someone@gitea.io",
   108      "avatar_url": "https://localhost:3000/avatars/1",
   109      "username": "gitea"
   110    },
   111    "sender": {
   112      "id": 1,
   113      "login": "gitea",
   114      "full_name": "Gitea",
   115      "email": "someone@gitea.io",
   116      "avatar_url": "https://localhost:3000/avatars/1",
   117      "username": "gitea"
   118    }
   119  }
   120  ```
   121  
   122  ### Example
   123  
   124  This is an example of how to use webhooks to run a php script upon push requests to the repository.
   125  In your repository Settings, under Webhooks, Setup a Gitea webhook as follows:
   126  
   127  - Target URL: http://mydomain.com/webhook.php
   128  - HTTP Method: POST
   129  - POST Content Type: application/json
   130  - Secret: 123
   131  - Trigger On: Push Events
   132  - Active: Checked
   133  
   134  Now on your server create the php file webhook.php
   135  
   136  ```
   137  <?php
   138  
   139  $secret_key = '123';
   140  
   141  // check for POST request
   142  if ($_SERVER['REQUEST_METHOD'] != 'POST') {
   143      error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
   144      exit();
   145  }
   146  
   147  // get content type
   148  $content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
   149  
   150  if ($content_type != 'application/json') {
   151      error_log('FAILED - not application/json - '. $content_type);
   152      exit();
   153  }
   154  
   155  // get payload
   156  $payload = trim(file_get_contents("php://input"));
   157  
   158  if (empty($payload)) {
   159      error_log('FAILED - no payload');
   160      exit();
   161  }
   162  
   163  // get header signature
   164  $header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
   165  
   166  if (empty($header_signature)) {
   167      error_log('FAILED - header signature missing');
   168      exit();
   169  }
   170  
   171  // calculate payload signature
   172  $payload_signature = hash_hmac('sha256', $payload, $secret_key, false);
   173  
   174  // check payload signature against header signature
   175  if ($header_signature !== $payload_signature) {
   176      error_log('FAILED - payload signature');
   177      exit();
   178  }
   179  
   180  // convert json to array
   181  $decoded = json_decode($payload, true);
   182  
   183  // check for json decode errors
   184  if (json_last_error() !== JSON_ERROR_NONE) {
   185      error_log('FAILED - json decode - '. json_last_error());
   186      exit();
   187  }
   188  
   189  // success, do something
   190  ```
   191  
   192  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.
   193  
   194  ### Authorization header
   195  
   196  **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.