How to use Global Webhooks

Drone FAQ
1

Global webhooks can be used to send an http webhook to a designated endpoint every time a system event occurs. Webhooks are currently triggered for the following system events:

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

Global webhooks are configured by passing the following environment variables to your Drone server instance:

DRONE_WEBHOOK_ENDPOINT=http://...
DRONE_WEBHOOK_SECRET=

The secret is used to sign the http request per the http signatures draft specification. The signature can be used to verify the authenticity and integrity of the webhook.

The secret should be 32 bytes:

$ openssl rand -hex 16
bea26a2221fd8090ea38720fc445eca6

Webhook Event Types

The webhook event type is included in the http request payload in the X-Drone-Event http header variable and can be used to determine the type and structure of the payload in the request body. Possible event types are:

  • user
  • repo
  • build

Webhook Actions

The webook payload includes an action field that defines the action being taken on the provided resource. For example, it indicates a user has been created or a repository has been enabled.

User Actions:

  • created
  • updated
  • deleted

Build Actions:

  • created
  • updated

Repository Actions:

  • enabled
  • disabled

Webhook Payload Structures

Definition of the user webhook payload structure, where the User resource is the json representation of a user.

{
  action: string
  user: User
}

Definition of the repository webhook payload structure, where the Repo resource is the json representation of a repository.

{
  action: string
  user: Repo
}

Definition of the repository webhook payload structure, where the Build resource is the json representation of a build.

{
  action: string
  repo: Repo
  build: Build
}
1 Like
2

When a build is cancelled, we also get an event?
Under build updated event?

3

Previously webhooks were not guaranteed when a build was cancelled. I recently patched the code to support this behavior. It is available in master, and will land in rc.6, which should be available in a couple of days.

1 Like
4

When a build is cancelled, we also get an event?

As I was searching for this myself, here is the updated information: When a build is cancelled, the status being triggered is called killed (see https://github.com/drone/drone/issues/2221).

It would be useful if the possible statuses were documented in the trigger documentation.

1 Like
5

How to verify request at endpoint with
DRONE_WEBHOOK_SECRET ?

I have used github webhook and it is very easy to verify github request.
Could you please explain in detail how to verify request coming through drone server.

This is payload i am recieving
Signature: keyId=“hmac-key”,algorithm=“hmac-sha256”,signature="****",headers=“date digest”

6

the hmac signature is created and can be validated as described in the http-signatures specification:
https://tools.ietf.org/html/draft-cavage-http-signatures

we provide a starter project you can use to handle the boilerplate:

you can also probably find libraries in your preferred language to help with validation. Here is a Go library that we are using:

7

Tried same but unable to create signature.
I am using python language and following below procedure: (correct me if i am wrong)

Digest: SHA-256=***

Date: Thu, 19 Dec 2019 07:09:14 GMT

Signature: keyId=“hmac-key”,algorithm=“hmac-sha256”,signature="***",headers=“date digest”

Now according to mentioned article

My key will be concatenation of date and sha

key = "date: Thu, 19 Dec 2019 07:09:14 GMT, digest: SHA-256=**** "

signature = hmac.new(“my secret”, msg=key, digestmod=hashlib.sha256).hexdigest()

and then compare signature with recieved signature right?

I am following above mentioned approach but still not able to match signature.

8

these libraries are confirmed to work with http signatures:

I recommend finding an existing python library to use with your implementation. If you are using a library and it is not working, I recommend reaching out to the library author to help you triage.

9

I don’t seem to be getting any “build completed” events. The last event I get is when the final step of my build changes from “pending” to “running”, no events are received after that. Any idea why this might be?