# Create a notification channel

`POST https://evohub.io/api/v1/notification-channels`

Part of the [Uptime API](https://docs-dev.evohub.io/uptime.md) reference · operationId `createNotificationChannel`.

Creates a channel. Link it to monitors afterwards with
`POST /api/v1/monitors/{id}/channels/{chId}`.

| `type` | `config` |
| --- | --- |
| `chat` | `chat_channel_id`: one of the IDs from `GET /api/v1/notification-channels/chat-apps`. EvoHub stores the channel's ID, name and app; any other key is ignored. |
| `webhook` | `url`: the address to POST to. `secret`: optional, sent back in the `X-Webhook-Secret` header. |
| `slack` | `url`: a Slack incoming webhook URL. Kept for existing channels; use `chat` for new Slack channels. |

A webhook receives a JSON body with `event` (`triggered` or
`resolved`), `monitor_id`, `monitor_name`, `monitor_url`, `cause`,
`timestamp` and, on `resolved`, `down_duration_seconds`.

Any other `type`, `email` included, is refused with 400
`VALIDATION_ERROR`.

The answer shows the channel as every later read will: the URL and
secret are not returned.

Requires the `uptime:channel:write` scope.

## Authorization

Any one of:

- `bearerKey`
- `headerKey`

Where:

- `bearerKey`: HTTP Bearer — An EvoHub API key (`evohub_…`) as a bearer token.
- `headerKey`: API key in the header `X-API-Key` — An EvoHub API key (`evohub_…`).

## Request body (required)

Content type: `application/json`

Type: `CreateChannelRequest`

- `name` (string, required, min length 1, max length 255)
- `type` (string, required, one of `chat`, `webhook`, `slack`)
- `config` (object): Depends on `type`; see the table above.
  - Other keys: string

## Responses

### 201 — The channel was created.

Content type: `application/json`

Type: `object`

- `data` (NotificationChannel)
  - `id` (string): Starts with `nch_`.
  - `org_id` (string)
  - `name` (string)
  - `type` (string, one of `chat`, `webhook`, `slack`)
  - `config` (object)
    - `url_host` (string)
    - `url_hint` (string)
    - `has_secret` (boolean)
    - `chat_channel_id` (string)
    - `chat_channel_name` (string)
    - `chat_channel_kind` (string)
    - Other keys: string
  - `created_at` (string (date-time))

### 400 — The body is not JSON (`INVALID_JSON`); `name` or `type` is missing or invalid, or a `chat` channel has no `config.chat_channel_id` (`VALIDATION_ERROR`); or the chat channel is not one of the organization's (`CHAT_CHANNEL_NOT_FOUND`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `MONITOR_NOT_FOUND`)
  - `message` (string, required, example `monitor not found`)
  - `request_id` (string)

### 401 — No API key was sent, or it is unknown, revoked or expired (`UNAUTHORIZED`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `MONITOR_NOT_FOUND`)
  - `message` (string, required, example `monitor not found`)
  - `request_id` (string)

### 403 — The key lacks the scope this endpoint needs (`FORBIDDEN`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `MONITOR_NOT_FOUND`)
  - `message` (string, required, example `monitor not found`)
  - `request_id` (string)

### 409 — Chat apps are not available, so a `chat` channel cannot be created (`CHAT_NOT_AVAILABLE`).

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `MONITOR_NOT_FOUND`)
  - `message` (string, required, example `monitor not found`)
  - `request_id` (string)

### 429 — Too many requests (`RATE_LIMITED`). Wait for `Retry-After` seconds.

Headers:

- `Retry-After` (integer): Seconds to wait before retrying.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `MONITOR_NOT_FOUND`)
  - `message` (string, required, example `monitor not found`)
  - `request_id` (string)

### 500 — Something went wrong on EvoHub's side (`INTERNAL_ERROR`). Retry later.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `MONITOR_NOT_FOUND`)
  - `message` (string, required, example `monitor not found`)
  - `request_id` (string)

### 502 — The organization's chat apps could not be read right now (`CHAT_UNAVAILABLE`). Retry shortly.

Content type: `application/json`

Type: `Error`

- `error` (object, required)
  - `code` (string, required, example `MONITOR_NOT_FOUND`)
  - `message` (string, required, example `monitor not found`)
  - `request_id` (string)

## Example request

```bash
curl -X POST 'https://evohub.io/api/v1/notification-channels' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <TOKEN>' \
  -d '{
  "name": "#ops-alerts",
  "type": "chat",
  "config": {
    "chat_channel_id": "slack:C04ABCDEF12"
  }
}'
```