Pipeline triggers API

The pipeline triggers API lets you manage a pipeline's pipeline triggers. Pipeline triggers are incoming webhook endpoints that create builds from external systems such as generic webhooks, GitHub, and Linear.

Public preview feature

The pipeline triggers feature, including this API, is currently in public preview. To provide feedback, contact the Buildkite Support team at support@buildkite.com.

Buildkite Pipelines doesn't support rotating a pipeline trigger's endpoint credentials in place. To replace a compromised endpoint, create a new pipeline trigger, point the sending system at its endpoint URL, then delete the old pipeline trigger.

Pipeline trigger data model

id UUID of the pipeline trigger.
url Canonical API URL of the pipeline trigger.
type Type of pipeline trigger. One of webhook, github, or linear.
label Label describing the pipeline trigger.
enabled Whether the pipeline trigger is enabled and accepting incoming webhook requests.
build Build configuration used for builds created by this pipeline trigger. Contains message, commit, branch, and environment_variables. The environment_variables array contains configured variable names, but not their values.
filter Filter expression that controls which incoming webhook deliveries create a build, or null if no filter is configured. Contains expression.
verification Webhook signature verification configuration, or null if verification isn't configured. Contains strategy, which is currently always hmac, and secret_hint, a masked version of the configured secret.
endpoint_url_hint A masked version of the pipeline trigger's endpoint URL that is safe to display or log.
endpoint_url The full endpoint URL that receives incoming webhook deliveries, including its plaintext token. Only present in the response from Create a pipeline trigger.
created_at When the pipeline trigger was created.
created_by User who created the pipeline trigger.
updated_at When the pipeline trigger was last updated.
updated_by User who last updated the pipeline trigger.
pipeline Reference to the parent pipeline, including its id, slug, and API url.

List pipeline triggers

Returns a paginated list of the pipeline triggers for a pipeline, with the most recently created first.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/triggers"

{
  "items": [
    {
      "id": "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
      "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/triggers/b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
      "type": "webhook",
      "label": "Deploy production",
      "enabled": true,
      "build": {
        "message": "Deploying production",
        "commit": "HEAD",
        "branch": "main",
        "environment_variables": ["DEPLOY_ENV"]
      },
      "filter": null,
      "verification": null,
      "endpoint_url_hint": "https://webhook.buildkite.com/deliver/bktr_XXXXXXXXXXXXXXXXXXXXet",
      "created_at": "2026-08-11T10:15:32.000Z",
      "created_by": {
        "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
        "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
        "name": "Sam Kim",
        "email": "sam@example.com",
        "avatar_url": "https://www.gravatar.com/avatar/example",
        "created_at": "2013-05-03T04:17:55.867Z"
      },
      "updated_at": "2026-08-11T10:15:32.000Z",
      "updated_by": {
        "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
        "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
        "name": "Sam Kim",
        "email": "sam@example.com",
        "avatar_url": "https://www.gravatar.com/avatar/example",
        "created_at": "2013-05-03T04:17:55.867Z"
      },
      "pipeline": {
        "id": "9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f",
        "slug": "my-pipeline",
        "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline"
      }
    }
  ],
  "links": {
    "self": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/triggers?per_page=30",
    "next": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/triggers?after=...&per_page=30"
  }
}

This endpoint uses cursor-based pagination. The response body is a JSON object with an items array and a links object. Use the next URL from links to fetch the next page. Follow that URL instead of constructing cursor values.

Full endpoint URLs, environment variable values, and verification secrets aren't included in list responses. Use endpoint_url_hint to identify a pipeline trigger without exposing its credentials.

Optional query string parameters:

per_page How many results to return per page.

Default: 30

Maximum: 100
after Return results after this cursor value. Mutually exclusive with before.
before Return results before this cursor value. Mutually exclusive with after.

Required scope: read_pipelines

Required permission: Full Access to the pipeline

Success response: 200 OK

Error responses:

400 Bad Request Invalid per_page or cursor value, or both after and before supplied

Get a pipeline trigger

Returns the details for a single pipeline trigger.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/triggers/{id}"

{
  "id": "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/triggers/b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
  "type": "github",
  "label": "GitHub pull requests",
  "enabled": true,
  "build": {
    "message": null,
    "commit": "HEAD",
    "branch": "main",
    "environment_variables": ["DEPLOY_ENV"]
  },
  "filter": {
    "expression": "webhook.headers[\"HTTP_X_GITHUB_EVENT\"] == \"pull_request\""
  },
  "verification": {
    "strategy": "hmac",
    "secret_hint": "XXXXXXXXXXXXXXXXXXXXet"
  },
  "endpoint_url_hint": "https://webhook.buildkite.com/deliver/bktr_XXXXXXXXXXXXXXXXXXXXet",
  "created_at": "2026-08-11T10:15:32.000Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-05-03T04:17:55.867Z"
  },
  "updated_at": "2026-08-11T10:15:32.000Z",
  "updated_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-05-03T04:17:55.867Z"
  },
  "pipeline": {
    "id": "9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f",
    "slug": "my-pipeline",
    "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline"
  }
}

The response doesn't include the full endpoint URL, environment variable values, or verification secret.

Required scope: read_pipelines

Required permission: Full Access to the pipeline

Success response: 200 OK

Error response: 404 Not Found when no pipeline trigger matches the given ID for this pipeline.

Filter webhook deliveries

Pipeline trigger filters use Common Expression Language (CEL). A filter must evaluate to true for an incoming webhook delivery to create a build.

Filter configuration is available only to organizations with webhook filtering enabled. Filter expressions have the following constraints:

  • Expressions can contain a maximum of 256 bytes.
  • Expressions can only reference the webhook variable.
  • CEL comprehensions such as all, exists, and map aren't supported.
  • The result must be a Boolean value. A delivery isn't run if its filter returns another type or fails to evaluate.

The webhook variable contains the following values:

webhook.id Identifier of the incoming webhook delivery.
webhook.created_at Time when the incoming webhook delivery was received, as an ISO 8601 string.
webhook.payload Parsed JSON payload of the incoming webhook delivery.
webhook.headers HTTP headers of the incoming webhook delivery. Header names use Rack-style keys, such as HTTP_X_GITHUB_EVENT.

For example, the following expression creates builds only for GitHub pull request events with an opened action:

webhook.headers["HTTP_X_GITHUB_EVENT"] == "pull_request" && webhook.payload.action == "opened"

Use the pipeline trigger deliveries API to inspect whether a delivery matched its filter.

Create a pipeline trigger

Creates a new pipeline trigger.

Endpoint URL visibility

The endpoint_url field contains the pipeline trigger's plaintext token and is only included in the response for this request. Save it to a secure location. Subsequent responses only include the masked endpoint_url_hint.

curl -H "Authorization: Bearer $TOKEN" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/triggers" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "webhook",
    "label": "Deploy production",
    "enabled": true,
    "build": {
      "message": "Deploying production",
      "commit": "HEAD",
      "branch": "main",
      "environment": {
        "DEPLOY_ENV": "production"
      }
    }
  }'

{
  "id": "b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline/triggers/b3a1e9f2-7c4d-4f1a-9e6c-2d8a5f7b1c3d",
  "type": "webhook",
  "label": "Deploy production",
  "enabled": true,
  "build": {
    "message": "Deploying production",
    "commit": "HEAD",
    "branch": "main",
    "environment_variables": ["DEPLOY_ENV"]
  },
  "filter": null,
  "verification": null,
  "endpoint_url": "https://webhook.buildkite.com/deliver/bktr_xxx-yyy-zzz",
  "endpoint_url_hint": "https://webhook.buildkite.com/deliver/bktr_XXXXXXXXXXXXXXXXXXXXzz",
  "created_at": "2026-08-11T10:15:32.000Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-05-03T04:17:55.867Z"
  },
  "updated_at": "2026-08-11T10:15:32.000Z",
  "updated_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQo=",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2013-05-03T04:17:55.867Z"
  },
  "pipeline": {
    "id": "9d1d1e9c-5e8f-4f9a-9b0c-1a2b3c4d5e6f",
    "slug": "my-pipeline",
    "url": "https://api.buildkite.com/v2/organizations/acme-inc/pipelines/my-pipeline"
  }
}

Required request body properties:

type Type of pipeline trigger to create. One of webhook, github, or linear. This value can't be changed after creation.

Example: "webhook"
label Non-empty label describing the pipeline trigger.

Example: "Deploy production"

Optional request body properties:

enabled Whether the pipeline trigger is enabled.

Default: true
build Build configuration used when this pipeline trigger creates a build. The object supports message, commit, branch, and environment. The environment value is a JSON object whose values must be strings. Omitted build fields use the pipeline defaults.

Example: { "branch": "main", "environment": { "DEPLOY_ENV": "production" } }
filter Filter with a required expression value that controls which deliveries create a build. Requires webhook filtering to be enabled for the organization. See Filter webhook deliveries for the expression contract.

Example: { "expression": "webhook.payload.action == \"opened\"" }
verification Webhook signature verification configuration. The object requires strategy, which must be hmac, and a non-empty secret. Supported for github and linear triggers. Generic webhook triggers don't support verification.

Example: { "strategy": "hmac", "secret": "your-signing-secret" }

Required scope: write_pipelines

Required permission: Full Access to the pipeline

Success response: 201 Created

Error responses:

400 Bad Request The request body isn't a valid JSON object
415 Unsupported Media Type The request doesn't use an application/json content type
422 Unprocessable Entity The request contains an unsupported field, invalid value, unavailable configuration, or the pipeline has reached its trigger limit

Update a pipeline trigger

Updates a pipeline trigger. Attributes omitted from the request body are left unchanged.

curl -H "Authorization: Bearer $TOKEN" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/triggers/{id}" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Updated pull requests",
    "enabled": false,
    "build": {
      "branch": "release"
    }
  }'

The response contains the updated pipeline trigger data model. The full endpoint URL, environment variable values, and verification secret aren't returned.

Optional request body properties:

label Non-empty label describing the pipeline trigger.
enabled Whether the pipeline trigger is enabled.
build Build fields to update. Set message, commit, or branch to null to restore its default. Omit environment to preserve the existing environment variables. Supplying environment replaces the entire environment map, so include every variable you want to retain. Set environment to an empty object to remove all environment variables.
filter Filter with a required expression value. Set filter to null to remove the filter. See Filter webhook deliveries for the expression contract.
verification Verification configuration with a required strategy value. When adding verification, provide a non-empty secret. When verification is already configured, omit secret to keep the existing secret, or provide a new value to replace it. Set verification to null to remove verification.

The type value can't be changed after a pipeline trigger is created.

Required scope: write_pipelines

Required permission: Full Access to the pipeline

Success response: 200 OK

Error responses: 400 Bad Request for invalid JSON, 404 Not Found when the trigger doesn't exist for this pipeline, 415 Unsupported Media Type for a non-JSON content type, and 422 Unprocessable Entity for invalid configuration.

Delete a pipeline trigger

Deletes a pipeline trigger. Its endpoint immediately stops accepting incoming webhook deliveries.

curl -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://api.buildkite.com/v2/organizations/{org.slug}/pipelines/{pipeline.slug}/triggers/{id}"

Required scope: write_pipelines

Required permission: Full Access to the pipeline

Success response: 204 No Content

Error response: 404 Not Found when no pipeline trigger matches the given ID for this pipeline.