Pipeline triggers

Create a new pipeline trigger

To create a new pipeline trigger using the Buildkite interface:

1. From your Buildkite dashboard, ensure that Pipelines is selected in the global navigation, and then select your pipeline.

2. Select your pipeline's Settings button > Triggers.

3. On the Triggers page, select the New Trigger button to create a new pipeline trigger.

4. Configure your pipeline trigger, by completing its fields, noting that the Description, Branch, and Commit fields are required to generate a unique endpoint.

   Description	The description for the pipeline trigger, which is its name in the list of existing triggers on the Triggers page.
   Build message	The message for your triggered build, which appears on the pipeline page as part of its build history. If none is specified, this value defaults to Triggered build.
   Commit	The commit ref the triggered build will run against. If none is specified, this value defaults to HEAD.
   Branch	The branch the triggered build will run against. If none is specified, this value defaults to main.
   Environment variables	Optional environment variables to set for the build. Each new environment variable should be entered on a new line. Example: FOO=bar BAZ=quux
   Enabled	Ensure this checkbox is selected to make the pipeline trigger active.

5. After completing these fields, select Create Trigger to create the pipeline trigger.

   

6. In the Trigger created successfully! message, follow the instructions to copy and save your webhook trigger's URL to a secure location, as you won't be able to see its value again through the Buildkite interface. The new webhook trigger appears in the list of existing triggers on the Triggers page.

That's it! You've completed creating your pipeline trigger. See the following section on Endpoint to learn more about the pipeline trigger and how it works, and you're now ready to invoke your trigger.

Endpoint

Each pipeline trigger has a unique endpoint with the following URL structure:

https://webhook.buildkite.com/deliver/bktr_************

All requests sent to this endpoint must be HTTP POST requests with application/json encoded bodies.

Response

A successful trigger request returns a 201 Created response with details about the created build:

{
  "id": "f62a1b4d-10f9-4790-bc1c-e2c3a0c80983"
}

Error responses

Invoke a pipeline trigger

To create a build using a webhook pipeline trigger, send an HTTP POST request to the trigger URL. Each trigger accepts a JSON payload, which is accessible to all build steps (see Accessing pipeline trigger data for details).

Here's an example using curl:

curl -H "Content-Type: application/json" \
  -X POST "https://webhook.buildkite.com/deliver/bktr_************" \
  -d '{
    "id": "P2LA89X",
    "message": "A fix for this incident is being developed",
    "trimmed": false,
    "type": "incident_status_update",
    "incident": {
      "html_url": "https://acme.pagerduty.com/incidents/PGR0VU2",
      "id": "PGR0VU2",
      "self": "https://api.pagerduty.com/incidents/PGR0VU2",
      "summary": "A little bump in the road",
      "type": "incident_reference"
    }
  }'

You've just created your first build using a pipeline trigger.

Accessing pipeline trigger data

JSON payloads sent to a pipeline trigger URL are accessible in all steps of the triggered build. You can retrieve the webhook payload using the Buildkite Agent CLI command buildite-agent meta-data.

Example

The following sample JSON payload is obtained from a GitHub webhook event for closing a GitHub pull request:

{
  "action": "closed",
  "number": 123,
  "organization": "Buildkite",
  "pull_request": {
    "url": "https://www.github.com/buildkite/dummy-repo",
    "id": 456,
    "number": 123,
    "state": "closed",
    "title": "Integrate into Buildkite pipeline triggers",
    "closed_at": "2025-10-14T02:14:39Z",
    "merged": false,
    "merged_at": null
  }
}

Accessing this JSON payload posted to your pipeline trigger endpoint can be done using the buildkite:webhook meta-data key, which is a special Buildkite meta-data key:

steps:
  - command: |
      WEBHOOK="$(buildkite-agent meta-data get buildkite:webhook)"
      ACTION="$(jq -r '.action' <<< "$WEBHOOK")"
      MERGED="$(jq -r '.pull_request.merged' <<< "$WEBHOOK")"

      if [[ "$ACTION" == "closed" && "$MERGED" == "false" ]]; then
        echo "PR was manually closed"
      fi

The buildkite:webhook meta-data itself is only available to builds triggered by any incoming webhook, and only for as long as the webhook data remains cached, which is typically for 7 days.

Limitations

Be aware that pipeline triggers have the following limitations:

• The authenticity of a webhook's JSON payload cannot be verified (for example, using HMAC signatures) by the pipeline trigger.
• A pipeline trigger's URL cannot be rotated. If the trigger's bkpt_ value has been compromised, you'll need to delete and re-create a new trigger with the same attributes.
• The Commit and Branch build attributes are only supported by their values defined in the pipeline trigger itself, when it was either created or last edited, and these values cannot be mapped from fields of the incoming webhook's JSON payload.
• A successful POST request to a pipeline trigger will always trigger a build. Pipeline triggers cannot be selectively triggered based on any content from the incoming webhook's JSON payload.
• Pipeline triggers can only be managed through the Buildkite interface. There is no support for managing pipeline triggers (that is, creating, editing or deleting pipeline triggers) through the Buildkite API.
• There is no Buildkite interface or API support for listing builds created from a pipeline trigger.
• Unlike JSON payloads, HTTP headers are not accessible to pipelines in requests to pipeline triggers.
• A pipeline trigger's webhook cannot be restricted by IP address.
• A pipeline trigger's JSON payload is limited to a maximum size of 5MB.
• Trigger URL endpoints have a request limit of 300 requests per hour.
• Webhook metadata payload retrieval is rate limited to 10 requests per minute per build.
• Each pipeline is limited to 10 configurable triggers.

Next steps

Learn more about how pipeline triggers integrate with other aspects of Buildkite Pipelines from the follow topic sections:

• Special meta-data—covers details on how to retrieve meta-data from a Buildkite pipeline.
• buildkite-agent meta-data CLI command—covers details on this actual meta-data retrieval command of the Buildkite Agent and all of its options.
• Incoming webhook security overview—provides information on the type of data logged by incoming webhooks.