System webhooks can be used to send an http request to a designated endpoint every time a system event occurs. Example system events:

User is created
User is deleted
Repository is activated
Repository is de-activated
Build is created
Build is updated or completed

Configuration

Create a shared secret used to sign the http request. This shared secret is to be provided to both the Drone server and your webhook receiver.
```
$ openssl rand -hex 16
bea26a2221fd8090ea38720fc445eca6
```
Update your Drone server configuration to include the webhook endpoint and the shared secret.
```
DRONE_WEBHOOK_ENDPOINT=http://...
DRONE_WEBHOOK_SECRET=bea26a2221fd8090ea38720fc445eca6
```

Request

Example webhook request headers:

1
2
3
4
5
6
7


POST / HTTP/1.1
Host: www.nowhere123.com
Date: Wed, 01 Jan 2020 00:00:00 GMT
Content-Type: application/json
Content-Length: 358
X-Drone-Event: user
Authorization: hmac-key",algorithm="hmac-sha256",signature="QrS16+RlRsFjXn5IVW8tWz+3ZRAypjpNgzehEuvJksk=

Example webhook request body:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
    "action": "created",
    "user": {
        "id": 1,
        "login": "octocat",
        "email": "octocat@github.com",
        "active": true,
        "admin": false,
        "machine": false,
        "syncing": false,
        "synced": 1564096971,
        "created": 1564096971,
        "updated": 1564096971,
        "last_login": 1564096971
    }
}

Authorization

The http request is signed per the http signatures draft specification use the shared secret. The receiver should use the signature to verify the authenticity and integrity of the webhook.

Third party libraries for http signature verification:

Events

The http request includes a header variable to determine he type of event. The following is a list of event types:

X-Drone-Event: user
X-Drone-Event: repo
X-Drone-Event: build

Actions

The payload includes an action field, which can be used to determine the type of action that was taken against the object. In the below example we see the user object was created.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16


{
    "action": "created",
    "user": {
        "id": 1,
        "login": "octocat",
        "email": "octocat@github.com",
        "active": true,
        "admin": false,
        "machine": false,
        "syncing": false,
        "synced": 1564096971,
        "created": 1564096971,
        "updated": 1564096971,
        "last_login": 1564096971
    }
}