---
id: notification-channels
title: Notification channels
sidebar_label: Notification channels
---

A channel is a destination for alerts. One channel serves as many
[monitors](./monitors.md) as you like.

Manage them at **Settings → Notifications**.

## Types

### Webhook

Posts JSON to a URL you choose.

| Setting |          |
| ------- | -------- |
| `url`   | Required |

```json
{
    "monitor": "API front door",
    "type": "http",
    "old_status": "up",
    "new_status": "down",
    "message": "HTTP 502",
    "time": "2026-07-28T09:14:02Z"
}
```

Alerts from a [metric alert](./metric-alerts.md) add `"server_name"` with the
server that breached. Other monitor types leave it out.

Any response of 300 or above counts as a delivery failure. The request times out
after 10 seconds.

### Discord

| Setting |                     |
| ------- | ------------------- |
| `url`   | Discord webhook URL |

Posts the alert as message content.

### Slack

| Setting |                            |
| ------- | -------------------------- |
| `url`   | Slack incoming webhook URL |

### Telegram

| Setting   |             |
| --------- | ----------- |
| `token`   | Bot token   |
| `chat_id` | Target chat |

### SMTP

| Setting                |                                                      |
| ---------------------- | ---------------------------------------------------- |
| `host`, `port`         | Required                                             |
| `from`, `to`           | Required                                             |
| `username`, `password` | Optional; auth is skipped when the username is empty |

Port `465` uses implicit TLS; anything else uses STARTTLS.

### Credentials are never read back

The SMTP `password`, the Telegram `token` and the webhook, Slack and Discord
`url`s come back from `GET /api/channels` as `••••••••` - a webhook URL is the
authorisation to post to that channel, so it is treated as a credential like
the rest. Writing that value back unchanged keeps the stored one, which is what
lets you rename a channel without retyping its password. Anything else you send
is written as given, so clearing the field clears the credential.

Alert emails look like the rest of the mail Vantage sends you.

## The message

Non-webhook channels all send the same one-line title:

```
[Vantage] API front door (http) is DOWN: HTTP 502
```

Recoveries read `recovered` in place of `is DOWN`. The webhook payload carries
the same information as fields, which is the one to use if you are routing into
something that needs to branch on status.

## Testing

Every channel has a **Test** button. It dispatches a fabricated down event for a
monitor called "Test monitor" and sends it the same way a real alert goes out, so
a test that arrives proves the credentials, the network path and the destination
as well as the form.

:::tip Test after every change
Channel settings are only exercised when something breaks, which is the worst
time to discover a stale webhook URL. Re-test after rotating a token.
:::

## Choosing destinations

- Use a **chat channel** for awareness, and make sure someone owns it.
- Use **SMTP** where a durable record matters.
- Use a **webhook** to reach an on-call system that does escalation properly.
  Vantage does not do escalation, rotas or acknowledgement; a webhook into
  something that does is the intended answer.