Reference

REST API notification channels

Manage delivery endpoints from code, and see what deleting one does to your existing routing.

curl https://api.drumbeats.io/v1/notification-channels \
  -H "X-API-Key: dk_live_<key>"

curl https://api.drumbeats.io/v1/notification-channels \
  -H "X-API-Key: dk_live_<key>"

A channel is one delivery endpoint: one Slack channel, one email address, one PagerDuty service. Channels go into groups, and groups are what monitors point at.

Any key can read. Writes need an account-scoped key with manage_notifications. A project-scoped key is read-only here.

Read channels#

GET /v1/notification-channels/types
GET /v1/notification-channels
GET /v1/notification-channels/<channel-id>

GET /v1/notification-channels/types
GET /v1/notification-channels
GET /v1/notification-channels/<channel-id>

The /types route returns the channel types available, which is what you want for rendering a picker.

Channel records carry the type, name, last-delivery timestamp, the most recent error string if a delivery failed, and the project owner. Secrets never come back on a read. Webhook URLs, Slack tokens, and PagerDuty keys are write-only.

The last_error field is worth polling. It is the only place a channel that has quietly stopped delivering will admit it.

Create a channel#

POST /v1/notification-channels

POST /v1/notification-channels

Needs manage_notifications.

curl -X POST https://api.drumbeats.io/v1/notification-channels \
  -H "X-API-Key: dk_live_<account-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project-id>",
    "name": "Ops Slack",
    "type": "SLACK",
    "config": { "webhook_url": "https://hooks.slack.com/services/…" }
  }'

curl -X POST https://api.drumbeats.io/v1/notification-channels \
  -H "X-API-Key: dk_live_<account-key>" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "<project-id>",
    "name": "Ops Slack",
    "type": "SLACK",
    "config": { "webhook_url": "https://hooks.slack.com/services/…" }
  }'

The config object's shape depends on type. Notification channels documents the fields for each, and webhooks covers the webhook config in full.

Anything you send in config is stored encrypted and never returned.

Update a channel#

PATCH /v1/notification-channels/<channel-id>

PATCH /v1/notification-channels/<channel-id>

Needs manage_notifications. Send only what changes. Re-test after any change to the destination or its credentials.

Delete a channel#

DELETE /v1/notification-channels/<channel-id>

DELETE /v1/notification-channels/<channel-id>

Needs the destroy scope, an account-scoped key, and the OWNER role on the project.

Next#

Notification channels for per-type setup and failure modes. REST API notification groups for bundling these. Alert logic for what decides a channel fires at all.