mirror of
https://codeberg.org/forgejo/forgejo.git
synced 2024-08-21 12:08:54 +02:00
_This is a different approach to #20267, I took the liberty of adapting some parts, see below_ ## Context In some cases, a weebhook endpoint requires some kind of authentication. The usual way is by sending a static `Authorization` header, with a given token. For instance: - Matrix expects a `Bearer <token>` (already implemented, by storing the header cleartext in the metadata - which is buggy on retry #19872) - TeamCity #18667 - Gitea instances #20267 - SourceHut https://man.sr.ht/graphql.md#authentication-strategies (this is my actual personal need :) ## Proposed solution Add a dedicated encrypt column to the webhook table (instead of storing it as meta as proposed in #20267), so that it gets available for all present and future hook types (especially the custom ones #19307). This would also solve the buggy matrix retry #19872. As a first step, I would recommend focusing on the backend logic and improve the frontend at a later stage. For now the UI is a simple `Authorization` field (which could be later customized with `Bearer` and `Basic` switches): ![2022-08-23-142911](https://user-images.githubusercontent.com/3864879/186162483-5b721504-eef5-4932-812e-eb96a68494cc.png) The header name is hard-coded, since I couldn't fine any usecase justifying otherwise. ## Questions - What do you think of this approach? @justusbunsi @Gusted @silverwind - ~~How are the migrations generated? Do I have to manually create a new file, or is there a command for that?~~ - ~~I started adding it to the API: should I complete it or should I drop it? (I don't know how much the API is actually used)~~ ## Done as well: - add a migration for the existing matrix webhooks and remove the `Authorization` logic there _Closes #19872_ Co-authored-by: Lunny Xiao <xiaolunwen@gmail.com> Co-authored-by: Gusted <williamzijl7@hotmail.com> Co-authored-by: delvh <dev.lh@web.de>
194 lines
5.2 KiB
Markdown
194 lines
5.2 KiB
Markdown
---
|
|
date: "2016-12-01T16:00:00+02:00"
|
|
title: "Webhooks"
|
|
slug: "webhooks"
|
|
weight: 10
|
|
toc: false
|
|
draft: false
|
|
menu:
|
|
sidebar:
|
|
parent: "features"
|
|
name: "Webhooks"
|
|
weight: 30
|
|
identifier: "webhooks"
|
|
---
|
|
|
|
# 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:
|
|
|
|
```
|
|
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",
|
|
"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"
|
|
}
|
|
}
|
|
```
|
|
|
|
### 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:
|
|
|
|
- Target URL: http://mydomain.com/webhook.php
|
|
- 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
|
|
$header_signature = isset($_SERVER['HTTP_X_GITEA_SIGNATURE']) ? $_SERVER['HTTP_X_GITEA_SIGNATURE'] : '';
|
|
|
|
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
|
|
|
|
**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.
|