Build webhook events

Events

Event Description
build.scheduled A build has been scheduled
build.running A build has started running
build.failing A build is failing
build.finished A build has finished
build.skipped A build has been skipped

Request body data

Property Type Description
build Build The build this notification relates to
pipeline Pipeline The pipeline this notification relates to
sender Object The user who created the webhook

Example request body:

{
  "event": "build.scheduled",
  "build": {
    "...": "..."
  },
  "pipeline": {
    "...": "..."
  },
  "sender": {
    "id": "8a7693f8-dbae-4783-9137-84090fce9045",
    "name": "Some Person"
  }
}

Job data not included

When using webhooks, the build object does not contain job data (as returned by calls to the Build API of Buildkite's REST API). Learn more about obtaining job data from Buildkite Pipelines using webhooks in Job events.

Finding out if a build is blocked

If a build is blocked, look for blocked: true in the build.finished event

Example request body for blocked build:

{
  "event": "build.finished",
  "build": {
    "...": "...",
    "blocked": true,
    "...": "..."
  },
  "pipeline": {
    "...": "..."
  },
  "sender": {
    "id": "0adfbc27-5f72-4a91-bf61-5693da0dd9c5",
    "name": "Some Person"
  }
}

To determine if an EventBridge notification is blocked

However, to determine if an EventBridge notification is blocked, look for "state": "blocked". , like in this sample Eventbridge request.

Trigger steps in build events

When a build contains trigger steps, the build.finished webhook will include the async field in the step configuration.

Example build.finished request body with trigger step:

{
  "event": "build.finished",
  "build": {
    "steps": [
      {
        "type": "trigger",
        "async": true,
        "...": "..."
      }
    ],
    "...": "..."
  },
  "pipeline": {
    "...": "..."
  },
  "sender": {
    "id": "8a7693f8-dbae-4783-9137-84090fce9045",
    "name": "Some Person"
  }
}

The async field indicates:

  • true: The trigger step continues immediately, regardless of the triggered build's success.
  • false: The trigger step waits for the triggered build to complete before continuing.