Notification services API

The notification services API lets you manage the organization-level integrations that send build and job notifications to services such as Slack, webhooks, Amazon EventBridge, Datadog, and OpenTelemetry.

Required permissions

These endpoints require both an API access token scope and sufficient organization access for the user who owns the token:

- List and get operations require the read_notification_services scope.

- Create, update, delete, enable, and disable operations require the write_notification_services scope.

The user who owns the token must be an organization administrator. Other organization members can use these endpoints when Manage Notification Services is enabled across the organization.

Notification service data model

Notification service endpoints return objects with the following fields:

`id`	UUID of the notification service.
`graphql_id`	GraphQL ID of the notification service, or `null` if unavailable.
`url`	Canonical API URL of the notification service.
`provider`	The notification service type, including a machine-readable `id`, such as `webhook`, `aws_event_bridge`, or `open_telemetry_tracing`, and a display `name`.
`description`	User-provided description of the notification service.
`enabled`	Whether the notification service is active.
`scope`	Determines which pipelines the service applies to: `all` for all pipelines, `some_projects` for selected pipelines, `some_teams` for pipelines in selected teams, or `some_clusters` for pipelines in selected clusters. For a `some_*` scope, `scope_uuids` identifies the selected pipelines, teams, or clusters.
`scope_uuids`	Pipeline UUIDs for `some_projects`, team UUIDs for `some_teams`, or cluster UUIDs for `some_clusters`. Empty when `scope` is `all`.
`branch_configuration`	Branch filter pattern. An empty string means all branches.
`build_states`	Object whose keys are build or job states and whose values indicate whether that state triggers a notification.
`settings`	Provider-specific configuration. See Settings and secret handling.
`created_at`	ISO 8601 timestamp of when the notification service was created.
`created_by`	User who created the notification service, or `null` when unavailable.

For example:

{
  "id": "9f0f9a19-1b88-4e37-98d8-c5a0cebcdb9a",
  "graphql_id": "Tm90aWZpY2F0aW9uU2VydmljZVdlYmhvb2stLS05ZjBmOWExOS0xYjg4LTRlMzctOThkOC1jNWEwY2ViY2RiOWE=",
  "url": "https://api.buildkite.com/v2/organizations/acme-inc/services/9f0f9a19-1b88-4e37-98d8-c5a0cebcdb9a",
  "provider": {
    "id": "webhook",
    "name": "Webhook"
  },
  "description": "Deploy notifications",
  "enabled": true,
  "scope": "all",
  "scope_uuids": [],
  "branch_configuration": "",
  "build_states": {
    "build_passed": false,
    "build_fixed": false,
    "build_failed": true,
    "build_blocked": false,
    "build_canceled": false,
    "build_failing": false,
    "job_activated": false
  },
  "settings": {
    "url": "https://example.com/buildkite-webhook",
    "version": 3,
    "token": "xxx-yyy-zzz",
    "token_mode": "token",
    "events": ["build.finished"],
    "tls_verify": true
  },
  "created_at": "2026-07-01T10:00:00.000Z",
  "created_by": {
    "id": "3d3c3bf0-7d58-4afe-8fe7-b3017d5504de",
    "graphql_id": "VXNlci0tLTNkM2MzYmYwLTdkNTgtNGFmZS04ZmU3LWIzMDE3ZDU1MDRkZQ==",
    "name": "Sam Kim",
    "email": "sam@example.com",
    "avatar_url": "https://www.gravatar.com/avatar/example",
    "created_at": "2025-01-01T00:00:00.000Z"
  }
}

Settings and secret handling

The settings object varies by provider. Secret handling mirrors the Buildkite interface:

Webhook token values are returned in full so that callers can verify webhook tokens or HMAC signatures.
Masked fields, such as the Datadog api_key and Amazon EventBridge aws_account_id, show only their final characters.
OAuth credentials such as access_token and refresh_token are omitted.
Slack incoming webhook URLs and encrypted OpenTelemetry headers are omitted.

When updating a service, sending a masked value back unchanged preserves the stored secret. Send a new plaintext value to replace it.

List notification services

Returns a cursor-paginated list of notification services, ordered from oldest to newest.

curl -H "Authorization: Bearer $TOKEN" \
  -X GET "https://api.buildkite.com/v2/organizations/{org.slug}/services?per_page=30"

The response contains notification service objects in items and pagination URLs in links:

{
  "items": [
    {
      "id": "9f0f9a19-1b88-4e37-98d8-c5a0cebcdb9a",
      "graphql_id": null,
      "url": "https://api.buildkite.com/v2/organizations/acme-inc/services/9f0f9a19-1b88-4e37-98d8-c5a0cebcdb9a",
      "provider": {
        "id": "datadog_pipeline_visibility",
        "name": "Datadog Pipeline Visibility"
      },
      "description": "Pipeline visibility",
      "enabled": true,
      "scope": "all",
      "scope_uuids": [],
      "branch_configuration": "",
      "build_states": {
        "build_passed": true,
        "build_fixed": true,
        "build_failed": true,
        "build_blocked": false,
        "build_canceled": false,
        "build_failing": false,
        "job_activated": false
      },
      "settings": {
        "api_key": "XXXXXXXXXXXXcdef",
        "datadog_site": "datadoghq.com",
        "datadog_tags": null
      },
      "created_at": "2026-07-01T10:00:00.000Z",
      "created_by": null
    }
  ],
  "links": {
    "self": "https://api.buildkite.com/v2/organizations/acme-inc/services?per_page=30",
    "next": "https://api.buildkite.com/v2/organizations/acme-inc/services?after=CURSOR&per_page=30"
  }
}

Optional query string parameters:

`per_page`	Number of results per page. Default: `30` Maximum: `100`
`after`	Return results after this cursor. Mutually exclusive with `before`.
`before`	Return results before this cursor. Mutually exclusive with `after`.

per_page

Number of results per page.

Default: 30

Maximum: 100

after Return results after this cursor. Mutually exclusive with before.

before Return results before this cursor. Mutually exclusive with after.

Required scope: read_notification_services

Success response: 200 OK

Get a notification service

Returns a notification service by UUID.

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

Required scope: read_notification_services

Success response: 200 OK

Error response: 404 Not Found when no notification service is found for the UUID in the organization.

Create a notification service

Creates a notification service. OAuth-managed slack_workspace and linear services must first be connected using the Buildkite interface, but can then be read, updated, deleted, enabled, and disabled using the API.

curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X POST "https://api.buildkite.com/v2/organizations/{org.slug}/services" \
  -d '{
    "provider": "webhook",
    "description": "Deploy notifications",
    "settings": {
      "url": "https://example.com/buildkite-webhook",
      "token": "xxx-yyy-zzz",
      "events": ["build.finished"]
    },
    "build_states": {
      "build_failed": true
    }
  }'

Request body properties:

`provider`	Required. Machine-readable notification service type, such as `webhook`, `aws_event_bridge`, or `open_telemetry_tracing`. See Providers.
`description`	User-provided description of the notification service.
`branch_configuration`	Branch filter pattern. For example, `main feature/*`. An empty string means all branches.
`scope`	Determines which pipelines the service applies to: `all` for all pipelines, `some_projects` for selected pipelines, `some_teams` for pipelines in selected teams, or `some_clusters` for pipelines in selected clusters. For a `some_*` scope, `scope_uuids` identifies the selected pipelines, teams, or clusters. Defaults to `all`.
`scope_uuids`	Pipeline UUIDs for `some_projects`, team UUIDs for `some_teams`, or cluster UUIDs for `some_clusters`. Omit when `scope` is `all`.
`build_states`	Object whose keys are build or job states and whose boolean values indicate whether that state triggers a notification. Supported keys are `build_passed`, `build_fixed`, `build_failed`, `build_blocked`, `build_canceled`, `build_failing`, and `job_activated`.
`settings`	Provider-specific configuration. See Providers.

Required scope: write_notification_services

Success response: 201 Created

Error response: 422 Unprocessable Entity when the request contains invalid, unavailable, unknown, or read-only fields.

Providers

The following providers can be created using the REST API:

`webhook`	Settings: `url` (required), `token`, `token_mode` (`token` or `signature`), `version`, `events`, and `tls_verify`.
`slack`	Slack or Slack-compatible incoming webhook. Settings: `url` (required) and `theme` (`text` or `emoji`).
`aws_event_bridge`	Settings: `aws_region` (required), `aws_account_id` (required 12-digit string), and `include_build_meta_data` when available for the organization.
`datadog_pipeline_visibility`	Settings: `api_key` (required), `datadog_site`, and `datadog_tags`.
`open_telemetry_tracing`	Settings: `endpoint` (required), `service_name`, `headers`, `resource_attributes`, and `tracestate` when available for the organization. Map values must be strings.
`event_log_api`	Available only when enabled for the organization. Settings: `events`.

Update a notification service

Updates only the fields in the request. Omitted top-level fields and settings remain unchanged.

curl -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -X PATCH "https://api.buildkite.com/v2/organizations/{org.slug}/services/{uuid}" \
  -d '{
    "description": "Production deploy notifications",
    "scope": "some_projects",
    "scope_uuids": ["16f3b56f-4934-4546-923c-287859851332"],
    "build_states": {
      "build_failed": true,
      "build_fixed": true
    }
  }'

The request accepts the same optional properties as create. If supplied, provider must match the existing provider because a service's provider cannot be changed.

Some settings have additional update restrictions:

Amazon EventBridge aws_region and aws_account_id are create-only.
A webhook can be upgraded to the latest payload version, but cannot be downgraded.
OAuth credentials and provider-managed metadata cannot be changed.
A Slack webhook URL connected using the Buildkite interface cannot be changed.

Resending unchanged restricted or masked values from a get response is allowed, so a get-update round trip does not overwrite secrets.

Required scope: write_notification_services

Success response: 200 OK

Error responses: 404 Not Found when the notification service cannot be found, or 422 Unprocessable Entity when the update is invalid.

Delete a notification service

Deletes a notification service.

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

Required scope: write_notification_services

Success response: 204 No Content

Error responses: 404 Not Found when the notification service cannot be found, or 422 Unprocessable Entity when Buildkite cannot remove the provider configuration.

Enable a notification service

Enables a notification service and clears any previous disabled or broken state. The response contains the updated notification service object.

curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/services/{uuid}/enable"

Required scope: write_notification_services

Success response: 200 OK

Error response: 404 Not Found when the notification service cannot be found.

Disable a notification service

Disables a notification service. The response contains the updated notification service object.

curl -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://api.buildkite.com/v2/organizations/{org.slug}/services/{uuid}/disable"

Required scope: write_notification_services

Success response: 200 OK

Error response: 404 Not Found when the notification service cannot be found.