How to use Global Webhooks


#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
}

#2

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