Webhooks overview
Buildkite webhooks send JSON payloads through HTTP requests to specific URL endpoints of third-party applications, which let these applications react to activities on the Buildkite platform as they happen.
Common use cases for implementing Buildkite webhooks include:
- Generating chat alerts in Slack that aren't covered by the Slack Workspace and Slack notification service integrations, as well as in other chat applications like Microsoft Teams.
- Automating infrastructure, such as scaling agents.
- Allowing your third party applications to:
- Ingest analytics or data on specific activities from the Buildkite platform.
- Display custom dashboards on data from the Buildkite platform.
Buildkite currently provides webhook support for both Pipelines and Test Engine.
Creating webhooks
Learn more about how to add Buildkite webhooks from the Add a webhook procedures for both Pipelines and Test Engine.
Pipelines webhooks also provide request headers to allow the authenticity of these webhook events to be verified.
Event families
Pipelines
Buildkite Pipelines supports the following categories of webhook events.
| Event family | Description |
|---|---|
| Build events | A pipeline build starts, fails, finishes, is scheduled, or is skipped. |
| Job events | A pipeline's job runs, finishes, is in a scheduled state, or is activated. |
| Agent events | A Buildkite Agent connects, disconnects, stops, is lost, or gets blocked. |
| Ping events | A webhook's notification configuration has changed. |
| Agent-token events | An agent token's registration has failed. |
| Integrations | Buildkite Pipeline events related to third-party application integrations. |
Test Engine
Buildkite Test Engine supports webhook events relating to changes in test states and labels.
Security best practices
When configuring your third party applications to receive Buildkite webhook events, ensure the following security measures are implemented:
- Serve your endpoint over TLS.
- Restrict accepted IP ranges for Buildkite webhooks to Buildkite's outgoing addresses.
- Ensure your endpoints only accept JSON payloads from Buildkite webhooks.