---
title: "Create alert channel"
method: POST
path: "/alert_channels"
---

# Create alert channel

`POST /alert_channels`

## Request

- Base URL: `https://app.yoping.me/api/v1`
- URL: `https://app.yoping.me/api/v1/alert_channels`
- Auth: API key in cookie `yp_session`

Creates an email, webhook, or Slack alert channel. An email channel to any address other than the account's own verified email must be confirmed via an emailed link before it can receive alerts; webhook and Slack channels are usable immediately.

## Request body

- AlertChannelRequest: Create/update payload for an alert channel. `config` is a union: only the fields for the channel's type are read (email: address; webhook: url and optional secret; slack: webhook_url). On update the type is fixed and omitted config fields keep their current values.
  - `type` 'email' | 'webhook' | 'slack', required
  - `config` object, required
    - `address` string, email: Email channels: destination address.
    - `url` string: Webhook channels: absolute http(s) URL with no userinfo.
    - `secret` string: Webhook channels: optional signing secret; a random one is generated when omitted at create.
    - `webhook_url` string: Slack channels: an https://hooks.slack.com/... URL.
  - `enabled` boolean: Update only: omit to keep the current value.

## Response `201`

Channel created (redacted view).

- object: Uniform success envelope: the payload is always under `data`.
  - `data` AlertChannel, required: Redacted channel view. `config` depends on type: email has `address`; webhook has `url` and boolean `has_secret`; slack has a redacted `url` like "hooks.slack.com/…XXXX". Secrets and full Slack URLs never appear.
    - `id` string, required
    - `type` 'email' | 'webhook' | 'slack', required
    - `verified_at` string, date-time, nullable, required: Null until the channel is confirmed; alerts are only sent to verified channels.
    - `enabled` boolean, required
    - `suppressed` boolean, required
    - `consecutive_failures` integer, required
    - `config` object, required
      - `address` string
      - `url` string
      - `has_secret` boolean

## Other responses

- `400`: Invalid input (code `validation_failed`): malformed JSON, a missing or out-of-range field, bad pagination parameters, or a rejected token.
- `401`: Not authenticated (code `unauthorized`): missing, invalid, or expired session; invalid login credentials; or a Bearer token, which this surface rejects.
- `403`: Forbidden. Code `forbidden` for a cross-origin (CSRF) request blocked by origin validation or for API-key management attempted without a browser session; `account_suspended` when a suspended account attempts a mutation; `account_deleted` when an account in its deletion grace window calls a non-exempt route.
- `429`: Too many requests (code `rate_limited`). A global per-IP budget of 300 requests/minute (burst 60) applies to every endpoint; login, signup, and test alerts have tighter dedicated limits.

---

[API](https://skmtc.dev/yoping/apis/yopingme-api.md) · [All operations](https://skmtc.dev/yoping/apis/yopingme-api/llms.txt) · [OpenAPI document](https://skmtc.dev/yoping/apis/yopingme-api/revisions/76d8deb40173?raw)