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, github_actions, 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. This field is null for github_actions triggers, which derive build attributes from the matched workflow event.
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.

GitHub Actions triggers don't accept a filter configuration and match supported workflow on declarations instead. See GitHub Actions pipeline setup for matching behavior and limitations.

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, github_actions, 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
create_webhook Whether to provision the GitHub repository webhook with generated HMAC verification when creating a github_actions trigger. Defaults to true; set to false to provision the webhook manually. Check the response's webhook_creation.status even when the API returns 201 Created. See Create a GitHub Actions pipeline trigger.
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, github_actions, and linear triggers. GitHub Actions webhook provisioning generates verification automatically when no secret is supplied. 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

Create a GitHub Actions pipeline trigger

Use a github_actions trigger for the recommended server-side workflow dispatch setup. The pipeline must use a GitHub.com repository connected through the full-access GitHub repository provider. Configure the pipeline's plugin without workflow or workflows so it runs the server-selected workflow.

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": "github_actions",
    "label": "GitHub Actions",
    "enabled": true,
    "create_webhook": true
  }'

The github_actions type doesn't accept build or filter, including an empty build object. The trigger derives build attributes from the matched workflow event. It creates one build per matching workflow per event, not a single build for all matched workflows.

Save the returned endpoint_url securely before leaving the creation response. It contains a one-time plaintext credential and isn't returned by subsequent reads. Webhook provisioning returns a webhook_creation object with a string status and a message that is a string or null. The status is configured when the webhook was provisioned, skipped when provisioning wasn't requested, or failed when provisioning was unsuccessful. The message is null for configured and skipped, and describes the error for failed. Check the status because 201 Created can still include webhook_creation.status: "failed": the trigger itself was created successfully.

If webhook provisioning fails, retain the trigger ID and endpoint URL, resolve the reported error, and repair the webhook setup for that trigger. The generated signing secret isn't retrievable. For manual recovery, update the existing trigger with a replacement HMAC verification secret, then configure the repository webhook with the saved endpoint URL and the same secret. Don't repeat the trigger creation request to retry provisioning, because that creates another trigger. Use the pipeline trigger deliveries API to verify deliveries after setup.

This request requires write_pipelines and Full Access to the pipeline, like other trigger creation requests.

Update a pipeline trigger

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

GitHub Actions triggers don't accept build or filter updates. Configure supported workflow on declarations instead.

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.