Webhooks allow you to monitor and respond to events within your Buildkite organization, providing a real time view of activity and allowing you to extend and integrate Buildkite into your systems.

Webhooks can be added and configured on your organization's Notification Services settings page.


You can subscribe to one or more of the following events:

Event Description
ping Webhook notification settings have changed
build.scheduled A build has been scheduled
build.running A build has started running
build.finished A build has finished
job.scheduled A job has been scheduled
job.started A command step job has started running on an agent
job.finished A job has finished
job.activated A block step job has been unblocked via the web or API
agent.connected An agent has connected
agent.lost An agent has been marked as lost
agent.disconnected An agent has disconnected
agent.stopping An agent is stopping
agent.stopped An agent has stopped

HTTP headers

The following HTTP headers are present in every webhook request, which allow you to identify the event that took place, and to verify the authenticity of the request:

X-Buildkite-Event The type of event

Example: build.scheduled

X-Buildkite-Token The token from your webhook configuration settings. It's presence in the header of the webhook confirms that you are the originator of the the webhook request

Example: 309c9c842d8565adec5d7469160059f9

HTTP request body

Each event’s data is sent JSON encoded in the request body. See each event’s documentation (agent, build, job, ping) to see which keys are available in the payload. For example:

  "event": "build.started",
  "build": {
    "keys": "vals"
  "sender": {
    "keys": "vals"

fast transitions and webhooks

Note that if a builds transitions between states very quickly, for example from blocked (`finished`) to unblocked (`running`), the webhook may be in a different state from the actual build. This is a known limitation of webhooks, in that they may represent a later version of the object than the one that triggered the event.

Example implementations

The following example repositories show how to receive a webhook event and trigger a LIFX powered build light. You can browse their source, fork them, and deploy them to Heroku directly from their GitHub readmes, or use them as an example to implement webhooks in your tool of choice.

:node: Node webhook example application github.com/buildkite/lifx-buildkite-build-light-node

:ruby: Ruby webhook example application github.com/buildkite/lifx-buildkite-build-light-ruby

:php: PHP webhook example application github.com/buildkite/lifx-buildkite-build-light-php

:node: Webtask.io webhook example application github.com/buildkite/lifx-buildkite-build-light-webtask

Build panda

Request logs

The last 50 webhook request and responses are saved, so you can debug and inspect your webhook. Each webhook’s request logs are available on the bottom of their settings page.