Notification Channels

A notification channel is an addressable target for alert notifications: a Slack workspace, a phone number, an email inbox, a webhook URL, or a CloudEvents sink. Channels are referenced by escalation-policy step targets.

Endpoints

Method	Path	Description	Scope
`GET`	`/api/v1/notification-channels`	List.	`notification_channels`
`POST`	`/api/v1/notification-channels`	Create.	`notification_channels`
`GET`	`/api/v1/notification-channels/{id}`	Read.	`notification_channels`
`PATCH`	`/api/v1/notification-channels/{id}`	Update.	`notification_channels`
`DELETE`	`/api/v1/notification-channels/{id}`	Delete. Fails if referenced by a policy or monitor.	`notification_channels`
`POST`	`/api/v1/notification-channels/{id}/test`	Send a test notification.	`notification_channels`

Channel types

Type	Config keys
`slack`	`workspace_id`, `channel_id` (tokens stored server-side via OAuth install).
`discord`	`webhook_url`, or `bot_token` + `channel_id`.
`telegram`	`bot_token`, `chat_id`.
`email`	`to`, `smtp_profile_id` (omit for SaaS-managed SMTP).
`sms`	`to` (E.164).
`voice`	`to` (E.164).
`webhook`	`url`, `method`, `headers`, `body_template`.
`ntfy`	`server`, `topic`, `auth_token`.
`pushover`	`user_key`, `app_token`.
`cloudevent_http`	`sink_url`, `mode` (`binary`/`structured`), optional `auth.oidc.*`, optional `accepted_replies.types`.

Create a channel

POST /api/v1/notification-channels

{
  "name": "Slack #oncall",
  "type": "slack",
  "config": {
    "workspace_id": "T0123",
    "channel_id": "C0456"
  },
  "enabled": true
}

Response: 201 Created with the channel document. config is returned with secrets redacted (*****).

CloudEvents HTTP channel (Pro+)

{
  "name": "SRE sink",
  "type": "cloudevent_http",
  "config": {
    "sink_url": "https://sre.example.com/cloudevents",
    "mode": "binary",
    "auth": {
      "oidc": {
        "token_url": "https://auth.example.com/oauth/token",
        "client_id": "yipyap-source",
        "client_secret": "…",
        "audience": "https://sre.example.com"
      }
    },
    "accepted_replies": {
      "types": ["run.yipyap.reply.alert.*"]
    }
  }
}

SSRF guard: every URL in a CloudEvents HTTP channel (sink_url, token_url, auth.oidc.issuer) is resolved and rejected if it maps to a private, loopback, link-local, or metadata address, both on write AND at every dispatch dial. Self-hosted operators may opt into private targets via YIPYAP_ALLOW_PRIVATE_CONTROL_PLANE_TARGETS=1.

Plan gate: cloudevent_http channels require Pro or Enterprise in SaaS. Free tier receives 402 plan_gate_blocked.

Test a channel

POST /api/v1/notification-channels/{id}/test

{ "severity": "warning", "message_override": "Test from YipYap" }

Sends a no-op notification. Returns 200 with the dispatch result (rendered payload, latency, target response status). Does not write to the alert timeline.

Enabled flag

Channels may be soft-disabled (enabled: false). Disabled channels are skipped by dispatch but remain referenced by policies; re-enable instead of re-creating.