> ## Documentation Index
> Fetch the complete documentation index at: https://docs.overwatchapp.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Alert channels API: create, update, and delete channels

> Create, list, retrieve, update, and delete alert channels; configure Slack, Discord, Teams, email, and webhook destinations; bind channels to monitors.

Alert channels define where Overwatch sends notifications when a monitor's status changes. You can configure channels for Slack, Discord, Microsoft Teams, email, and generic webhooks. Once a channel exists, you bind it to one or more monitors by passing `alertChannelIds` when creating or updating a monitor.

***

## List alert channels

```
GET /api/v1/alerts
```

Returns all alert channels in your organization, including which monitors each channel is bound to.

### Response

```json theme={null}
{
  "data": [
    {
      "id": "alc_01j...",
      "name": "Ops Slack",
      "type": "SLACK",
      "config": { "webhookUrl": "https://hooks.slack.com/services/..." },
      "enabled": true,
      "bindings": [
        { "monitorId": "mon_01j...", "alertChannelId": "alc_01j..." }
      ],
      "createdAt": "2025-01-01T00:00:00.000Z",
      "updatedAt": "2025-04-15T10:00:00.000Z"
    }
  ]
}
```

### Example

```bash theme={null}
curl https://overwatchapp.dev/api/v1/alerts \
  -H "Authorization: Bearer $API_KEY"
```

***

## Create an alert channel

```
POST /api/v1/alerts
```

Creates a new alert channel. Requires `admin` or `owner` role. Returns `402` if your organization has no active subscription, and `422` with `"upgrade": true` if you have reached your alert channel limit.

### Request body

<ParamField body="name" type="string" required>
  Display name for the channel.
</ParamField>

<ParamField body="type" type="string" required>
  Channel type. One of `SLACK`, `DISCORD`, `TEAMS`, `EMAIL`, `WEBHOOK`.
</ParamField>

<ParamField body="config" type="object" required>
  Type-specific configuration. See [Config by channel type](#config-by-channel-type) below.
</ParamField>

<ParamField body="enabled" type="boolean">
  Whether the channel should fire alerts. Defaults to `true`.
</ParamField>

### Config by channel type

<CodeGroup>
  ```json Slack theme={null}
  {
    "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
  }
  ```

  ```json Discord theme={null}
  {
    "webhookUrl": "https://discord.com/api/webhooks/1234567890/XXXXXXXXXXXXXXXX"
  }
  ```

  ```json Teams theme={null}
  {
    "webhookUrl": "https://your-org.webhook.office.com/webhookb2/..."
  }
  ```

  ```json Email theme={null}
  {
    "to": "oncall@example.com"
  }
  ```

  ```json Webhook theme={null}
  {
    "url": "https://api.example.com/overwatch-events",
    "secret": "optional-hmac-secret"
  }
  ```
</CodeGroup>

For `WEBHOOK` channels, the optional `secret` is used to sign outgoing payloads with an HMAC signature so your endpoint can verify requests came from Overwatch.

### Response

Returns `201 Created` with the new channel object.

```json theme={null}
{
  "data": {
    "id": "alc_01j...",
    "name": "Ops Slack",
    "type": "SLACK",
    "config": { "webhookUrl": "https://hooks.slack.com/services/..." },
    "enabled": true,
    "createdAt": "2025-04-15T10:00:00.000Z",
    "updatedAt": "2025-04-15T10:00:00.000Z"
  }
}
```

### Example

```bash theme={null}
curl -X POST https://overwatchapp.dev/api/v1/alerts \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Ops Slack",
    "type": "SLACK",
    "config": { "webhookUrl": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXX" }
  }'
```

***

## Get an alert channel

```
GET /api/v1/alerts/:id
```

Returns a single alert channel by ID, including its monitor bindings.

### Path parameters

<ParamField path="id" type="string" required>
  The alert channel ID.
</ParamField>

### Response

```json theme={null}
{
  "data": {
    "id": "alc_01j...",
    "name": "Ops Slack",
    "type": "SLACK",
    "config": { "webhookUrl": "https://hooks.slack.com/services/..." },
    "enabled": true,
    "bindings": [],
    "createdAt": "2025-01-01T00:00:00.000Z",
    "updatedAt": "2025-04-15T10:00:00.000Z"
  }
}
```

### Example

```bash theme={null}
curl https://overwatchapp.dev/api/v1/alerts/$CHANNEL_ID \
  -H "Authorization: Bearer $API_KEY"
```

***

## Update an alert channel

```
PATCH /api/v1/alerts/:id
```

Updates one or more fields on an alert channel. All body fields are optional. Requires `admin` or `owner` role.

### Path parameters

<ParamField path="id" type="string" required>
  The alert channel ID.
</ParamField>

### Request body

<ParamField body="name" type="string">
  New display name.
</ParamField>

<ParamField body="config" type="object">
  Updated type-specific configuration. Must match the channel's existing type.
</ParamField>

<ParamField body="enabled" type="boolean">
  Set to `false` to silence alerts from this channel without deleting it.
</ParamField>

### Response

Returns the updated channel object with `200 OK`.

### Example

```bash theme={null}
curl -X PATCH https://overwatchapp.dev/api/v1/alerts/$CHANNEL_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "enabled": false }'
```

***

## Delete an alert channel

```
DELETE /api/v1/alerts/:id
```

Permanently deletes an alert channel. Any monitor bindings to this channel are also removed. Requires `admin` or `owner` role.

### Path parameters

<ParamField path="id" type="string" required>
  The alert channel ID.
</ParamField>

### Response

```json theme={null}
{
  "data": { "id": "alc_01j..." }
}
```

### Example

```bash theme={null}
curl -X DELETE https://overwatchapp.dev/api/v1/alerts/$CHANNEL_ID \
  -H "Authorization: Bearer $API_KEY"
```

***

## Binding channels to monitors

Alert channels do not fire on their own — you must bind them to at least one monitor. You do this by passing `alertChannelIds` when creating or updating a monitor:

```bash theme={null}
# Bind a channel when creating a monitor
curl -X POST https://overwatchapp.dev/api/v1/monitors \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "API health",
    "type": "HTTP",
    "config": { "url": "https://api.example.com/health", "interval": 60 },
    "alertChannelIds": ["alc_01j..."]
  }'

# Update bindings on an existing monitor
curl -X PATCH https://overwatchapp.dev/api/v1/monitors/$MONITOR_ID \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "alertChannelIds": ["alc_01j...", "alc_02j..."] }'
```

Passing `alertChannelIds` in a `PATCH` replaces the full set of bindings. To remove all bindings, pass an empty array.