Permalink
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
76 lines (55 sloc) 3.58 KB
# Webhooks
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.
<%= toc %>
## Events
You can subscribe to one or more of the following events:
<table>
<thead>
<tr><th>Event</th><th>Description</th></tr>
</thead>
<tbody>
<tr><th>ping</th><td>Webhook notification settings have changed</td></tr>
<tr><th>build.scheduled</th><td>A build has been scheduled</td></tr>
<tr><th>build.running</th><td>A build has started running</td></tr>
<tr><th>build.finished</th><td>A build has finished</td></tr>
<tr><th>job.scheduled</th><td>A job has been scheduled</td></tr>
<tr><th>job.started</th><td>A job has started</td></tr>
<tr><th>job.finished</th><td>A job has finished</td></tr>
<tr><th>job.activated</th><td>A job has been activated</td></tr>
<tr><th>agent.connected</th><td>An agent has connected</td></tr>
<tr><th>agent.lost</th><td>An agent has been marked as lost</td></tr>
<tr><th>agent.disconnected</th><td>An agent has disconnected</td></tr>
<tr><th>agent.stopping</th><td>An agent is stopping</td></tr>
<tr><th>agent.stopped</th><td>An agent has stopped</td></tr>
</tbody>
</table>
## 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:
<table>
<tbody>
<tr><th><code>X-Buildkite-Event</code></th><td>The type of event<p class="Docs__api-param-eg"><em>Example:</em> <code>build.scheduled</code></p></td></tr>
<tr><th><code>X-Buildkite-Token</code></th><td>The token from your webhook configuration settings, used to verify the authenticity of the webhook request<p class="Docs__api-param-eg"><em>Example:</em> <code>309c9c842d8565adec5d7469160059f9</code></p></td></tr>
</tbody>
</table>
## HTTP request body
Each event’s data is sent JSON encoded in the request body. See each event’s documentation to see which keys are available in the payload. For example:
```json
{
"event": "build.started",
"build": {
"keys": "vals"
},
"sender": {
"keys": "vals"
}
}
```
## 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 simply use them as an example to implement webhooks in your tool of choice.
<a class="Docs__example-repo" href="https://github.com/buildkite/lifx-buildkite-build-light-node">:node: Node webhook example application <span class="repo">github.com/buildkite/lifx-buildkite-build-light-node</span></a>
<a class="Docs__example-repo" href="https://github.com/buildkite/lifx-buildkite-build-light-ruby">:ruby: Ruby webhook example application <span class="repo">github.com/buildkite/lifx-buildkite-build-light-ruby</span></a>
<a class="Docs__example-repo" href="https://github.com/buildkite/lifx-buildkite-build-light-php">:php: PHP webhook example application <span class="repo">github.com/buildkite/lifx-buildkite-build-light-php</span></a>
<a class="Docs__example-repo" href="https://github.com/buildkite/lifx-buildkite-build-light-webtask">:node: Webtask.io webhook example application <span class="repo">github.com/buildkite/lifx-buildkite-build-light-webtask</span></a>
<%= image "panda_light.gif", alt: "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.