# Alerts

## Channels

| Channel | Setup | Notes |
|---|---|---|
| Email | One to five addresses | Sent through the server's providers: Brevo first, Resend if Brevo fails |
| Discord | A channel's webhook URL (Server settings, Integrations, Webhooks) | Colour-coded embeds |
| Webhook | Any HTTPS URL, an optional signing secret and headers | JSON body, signed |

Each channel picks the events it wants: **down**, **up**, **slow**, **flapping**, **cert** (expiry warnings), **reminder** and **notice** (Farsight's own news, such as "offline from 02:14 to 02:19"). A monitor can be limited to some channels; by default it uses them all.

Press **Send test** after adding a channel. **Alerts sent**, under Alerts, shows one row per alert with each channel's result ("Owner email · sent", "Pager webhook · failed after 3 tries: HTTP 410 Gone"); an incident's page tells the same for that incident.

## Grouping

Alerts for a channel wait 20 seconds from the first one, and everything that arrives in that window goes out as one message. A whole server going down is one email, not twenty. A monitor that goes down and back up inside the window shows as one "blip".

## Reliability

Every message is written down before it is sent and retried if it fails: after 10 s, 30 s, 2 m, 10 m, 30 m, then hourly for a day. A provider that keeps refusing (a wrong URL) stops after three tries and the channel shows as failing.

Email has a daily limit of 80 so a storm cannot use up a shared provider quota; the 81st becomes one "email paused until tomorrow" notice. Discord and webhooks keep working.

## Reminders, muting, flapping

- **Remind every** (per monitor): while it stays down, send a reminder this often.
- **Mute**: checks run, alerts are held and logged as muted.
- **Flapping**: one alert, then silence until it settles.

## Webhook format

```
POST <your url>
Content-Type: application/json
X-Farsight-Timestamp: 1791000000
X-Farsight-Signature: <hex HMAC-SHA256 of "<timestamp>.<body>" under your secret>

{"farsight": "1", "events": [{"type": "down", "at": "...", "title": "Down: API", "message": "got 502 Bad Gateway, expected 200-299",
  "monitor": {"id": 3, "name": "API", "slug": "api", "group": "Production", "target": "https://...", "url": "https://farsight.example.com/#/m/3"},
  "error": {"code": "status_mismatch", "message": "..."}}]}
```

Check the signature and reject timestamps older than a few minutes.