0
0
Fork 0
mirror of https://codeberg.org/forgejo/docs.git synced 2024-12-23 22:20:43 -05:00
forgejo-docs/docs/user/webhooks.md

189 lines
5.3 KiB
Markdown
Raw Normal View History

2023-03-04 04:42:11 -05:00
---
2023-03-04 04:48:23 -05:00
title: 'Webhooks'
license: 'Apache-2.0'
origin_url: 'https://github.com/go-gitea/gitea/blob/faa28b5a44912f1c63afddab9396bae9e6fe061c/docs/content/doc/usage/webhooks.en-us.md'
2023-03-04 04:42:11 -05:00
---
2023-03-04 04:48:23 -05:00
Forgejo supports webhooks for repository events. This can be configured in the settings
2023-03-04 04:42:11 -05:00
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:
2023-03-04 04:48:23 -05:00
- Forgejo (can also be a GET request)
2023-03-04 04:42:11 -05:00
- Gitea (can also be a GET request)
- Gogs
- Slack
- Discord
- Dingtalk
- Telegram
- Microsoft Teams
- Feishu
- Wechatwork
- Packagist
### Event information
2023-03-04 04:48:23 -05:00
The following is an example of event information that will be sent by Forgejo to
2023-03-04 04:42:11 -05:00
a Payload URL:
```
2023-03-04 04:48:23 -05:00
X-Forgejo-Delivery: f6266f16-1bf3-46a5-9ea4-602e06ead473
X-Forgejo-Event: push
2023-03-04 04:42:11 -05:00
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
```
```json
{
"secret": "3gEsCfjlV2ugRwgpU#w1*WaW*wa4NXgGmpCfkbG3",
"ref": "refs/heads/develop",
"before": "28e1879d029cb852e4844d9c718537df08844e03",
"after": "bffeb74224043ba2feb48d137756c8a9331c449a",
2023-03-04 04:48:23 -05:00
"compare_url": "http://localhost:3000/forgejo/webhooks/compare/28e1879d029cb852e4844d9c718537df08844e03...bffeb74224043ba2feb48d137756c8a9331c449a",
2023-03-04 04:42:11 -05:00
"commits": [
{
"id": "bffeb74224043ba2feb48d137756c8a9331c449a",
"message": "Webhooks Yay!",
2023-03-04 04:48:23 -05:00
"url": "http://localhost:3000/forgejo/webhooks/commit/bffeb74224043ba2feb48d137756c8a9331c449a",
2023-03-04 04:42:11 -05:00
"author": {
2023-03-04 04:48:23 -05:00
"name": "Forgejo",
"email": "someone@forgejo.org",
"username": "forgejo"
2023-03-04 04:42:11 -05:00
},
"committer": {
2023-03-04 04:48:23 -05:00
"name": "Forgejo",
"email": "someone@forgejo.org",
"username": "forgejo"
2023-03-04 04:42:11 -05:00
},
"timestamp": "2017-03-13T13:52:11-04:00"
}
],
"repository": {
"id": 140,
"owner": {
"id": 1,
2023-03-04 04:48:23 -05:00
"login": "forgejo",
"full_name": "Forgejo",
"email": "someone@forgejo.org",
2023-03-04 04:42:11 -05:00
"avatar_url": "https://localhost:3000/avatars/1",
2023-03-04 04:48:23 -05:00
"username": "forgejo"
2023-03-04 04:42:11 -05:00
},
"name": "webhooks",
2023-03-04 04:48:23 -05:00
"full_name": "forgejo/webhooks",
2023-03-04 04:42:11 -05:00
"description": "",
"private": false,
"fork": false,
2023-03-04 04:48:23 -05:00
"html_url": "http://localhost:3000/forgejo/webhooks",
"ssh_url": "ssh://forgejo@localhost:2222/forgejo/webhooks.git",
"clone_url": "http://localhost:3000/forgejo/webhooks.git",
2023-03-04 04:42:11 -05:00
"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,
2023-03-04 04:48:23 -05:00
"login": "forgejo",
"full_name": "Forgejo",
"email": "someone@forgejo.org",
2023-03-04 04:42:11 -05:00
"avatar_url": "https://localhost:3000/avatars/1",
2023-03-04 04:48:23 -05:00
"username": "forgejo"
2023-03-04 04:42:11 -05:00
},
"sender": {
"id": 1,
2023-03-04 04:48:23 -05:00
"login": "forgejo",
"full_name": "Forgejo",
"email": "someone@forgejo.org",
2023-03-04 04:42:11 -05:00
"avatar_url": "https://localhost:3000/avatars/1",
2023-03-04 04:48:23 -05:00
"username": "forgejo"
2023-03-04 04:42:11 -05:00
}
}
```
### Example
This is an example of how to use webhooks to run a php script upon push requests to the repository.
2023-03-04 04:48:23 -05:00
In your repository Settings, under Webhooks, Setup a Forgejo webhook as follows:
2023-03-04 04:42:11 -05:00
- Target URL: http://example.com/webhook.php
2023-03-04 04:42:11 -05:00
- HTTP Method: POST
- POST Content Type: application/json
- Secret: 123
- Trigger On: Push Events
- Active: Checked
Now on your server create the php file webhook.php
```
<?php
$secret_key = '123';
// check for POST request
if ($_SERVER['REQUEST_METHOD'] != 'POST') {
error_log('FAILED - not POST - '. $_SERVER['REQUEST_METHOD']);
exit();
}
// get content type
$content_type = isset($_SERVER['CONTENT_TYPE']) ? strtolower(trim($_SERVER['CONTENT_TYPE'])) : '';
if ($content_type != 'application/json') {
error_log('FAILED - not application/json - '. $content_type);
exit();
}
// get payload
$payload = trim(file_get_contents("php://input"));
if (empty($payload)) {
error_log('FAILED - no payload');
exit();
}
// get header signature
2023-03-04 04:48:23 -05:00
$header_signature = isset($_SERVER['HTTP_X_FORGEJO_SIGNATURE']) ? $_SERVER['HTTP_X_FORGEJO_SIGNATURE'] : '';
2023-03-04 04:42:11 -05:00
if (empty($header_signature)) {
error_log('FAILED - header signature missing');
exit();
}
// 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
```
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
2023-03-04 05:06:22 -05:00
Forgejo webhooks can be configured to send an [authorization header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Authorization) to the target.
![screenshot of the webhook definition webpage](../../../../images/v1.21/user/webhooks/authorization-header.png)
2023-03-04 05:06:22 -05:00
The authentication string is stored encrypted in the database.