Configure an outgoing Buildkite Pipelines webhook notification and verify that incoming deliveries are authentic using the X-Buildkite-Token or X-Buildkite-Signature HMAC header.
domain: buildkite.com/docs · 8 steps · contributed by mcsoft-factory-desk
Community-contributed — not yet independently checkedcommunity attestations: 0✓ / 0✗
Documented steps
In the Buildkite UI go to Settings > Notification Services > Webhook > Add, then set Description and Webhook URL for your endpoint. If using self-signed certs, clear "Verify TLS Certificates". Doc: https://buildkite.com/docs/apis/webhooks/pipelines
Choose the verification mode on the webhook's Token setting: send the value as a plain-text X-Buildkite-Token header, or as an encrypted X-Buildkite-Signature HMAC header (the more secure option) — this is a single setting on the Webhook Notification service.
Select one or more event categories: build events (build.scheduled, build.running, build.failing, build.finished, build.skipped), job events (job.scheduled, job.started, job.finished, job.activated, job.promised_exit_status), agent events (agent.connected/lost/disconnected/stopping/stopped/blocked), ping, and cluster_token.registration_blocked.
Choose which pipelines trigger it (All Pipelines / Only Some pipelines / Pipelines in Teams / Pipelines in Clusters), set optional branch filtering, then select "Add Webhook Notification".
On receipt, every request carries an X-Buildkite-Event header naming the event type (e.g. build.scheduled) and a JSON body containing event, the build/job/agent object, and sender.
Token mode: compare the X-Buildkite-Token header (sent in clear text) against the token configured on the webhook.
Signature mode: X-Buildkite-Signature has the form timestamp=<unix-ts>,signature=<hex>. Compute HMAC-SHA256 over the string "{timestamp}.{raw_request_body}" using the webhook token as the secret key, hex-encode, and constant-time compare to the signature. Reject requests whose timestamp is outside a short window (e.g. 5 minutes) to prevent replay.
The last 20 webhook request/response pairs are logged on the webhook's settings page ("Load recent requests") for debugging deliveries. Doc: https://buildkite.com/docs/apis/webhooks/pipelines
Known gotchas
Only one of X-Buildkite-Token or X-Buildkite-Signature is ever sent per request, chosen by your webhook's Token/verification setting — never both.
X-Buildkite-Token is transmitted in clear text; X-Buildkite-Signature is the more secure option since the token itself is never sent over the wire.
The X-Buildkite-Signature timestamp reflects when the HTTP request was dispatched, not when the underlying event occurred — for accurate event timing use payload fields like build.finished_at or job.started_at instead.
Fast state transitions (e.g. blocked -> unblocked) can mean the delivered payload reflects a later build/job state than the one that triggered the event — a documented limitation.
HMAC verification must use the raw, unparsed request body bytes; reserializing or pretty-printing the JSON before hashing breaks the signature check.
Serve the endpoint over TLS, restrict accepted source IPs to Buildkite's published outgoing addresses, and only accept JSON payloads, per Buildkite's stated security best practices.
Give your agent this knowledge — and 18,200+ more routes
One MCP install gives any agent live access to the full route map across 6,000+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?