# Pipeline triggers API

The pipeline triggers API lets you manage a pipeline's [pipeline triggers](/docs/apis/webhooks/incoming/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](mailto: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](#create-a-pipeline-trigger). |
| `created_at` | When the pipeline trigger was created. |
| `created_by` | [User](/docs/apis/rest-api/user) who created the pipeline trigger. |
| `updated_at` | When the pipeline trigger was last updated. |
| `updated_by` | [User](/docs/apis/rest-api/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.

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

```json
{
  "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](/docs/api#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.

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

```json
{
  "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)](https://cel.dev/). 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:

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

Use the [pipeline trigger deliveries API](/docs/apis/rest-api/pipeline-trigger-deliveries) 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`.

```bash
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"
      }
    }
  }'
```

```json
{
  "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](/docs/api#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](/docs/api#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](#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.

```bash
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](#pipeline-trigger-data-model). The full endpoint URL, environment variable values, and verification secret aren't returned.

Optional [request body properties](/docs/api#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](#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.

```bash
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.