Alerts and reports · 2 of 4
Alert channels
Where alerts go: ntfy, Discord, email, PagerDuty and signed webhooks, each with a minimum severity. Secrets sealed in the database or kept in files, and critical alerts never by email alone.
Add channels under Configure › Alerts and press Send a test on each.
Or keep them in obs-beacond.yaml under alerts.channels (below).
Every channel has an id, a type and a minimum severity, min:
warning (the default), serious or critical.
| Type | Needs | Notes |
|---|---|---|
| ntfy | The topic; optionally the server (default ntfy.sh) and an access token | Priority urgent for critical, high for serious. Point it at your own ntfy server if you have one |
| Discord | A channel's webhook URL | Coloured by severity. With mention_critical, @here when something goes critical |
The SMTP server (host:port), password, from and to; optionally a username (default from's address) |
Authenticated submission only: STARTTLS on 587, TLS on 465. Refuses a server without TLS | |
| PagerDuty | An Events API v2 integration key; EU accounts set the server to https://events.eu.pagerduty.com |
Follows each incident: alerting triggers it, acknowledging here acknowledges it there, resolving resolves it. Repeats aren't sent: PagerDuty's escalation policy does that. The test sends a change event, which pages nobody |
| Webhook | A URL; optionally a signing secret | A JSON POST, below |
Critical alerts must reach at least one channel that isn't email. If mail is what's down, the email never arrives. obs-beacond won't start with a config that breaks this rule, and the web interface refuses a change that would.
A failed send is tried again after 5 and 30 seconds. With a database, each notice waits there until it's sent, so a restart doesn't lose it.
Webhooks
Each notice is a JSON POST:
{
"kind": "firing",
"id": "B-0142",
"severity": "critical",
"title": "db1 has gone silent",
"detail": "No report for 2m14s. Its agent, the host or the link to it is down.",
"host": "db1",
"url": "https://obs.example.org/hosts/db1",
"since": "2026-11-15T09:12:40Z"
}
kind is firing, escalated (got worse), still (a repeat), resolved,
test or digest. With a signing secret, the X-Beacon-Signature header
is sha256= and the HMAC-SHA256 of the body with that secret: check it
before you trust the body.
Secrets
A channel's topic, token, webhook URL, signing secret, password or integration key is entered once in the web interface and kept in the database, sealed with the state key. It's never shown again: the form says a secret is set, and leaving the field blank keeps it. The audit log says when a secret was replaced, never what it is.
Export YAML leaves secrets out, so the file is safe to keep or share.
In the config file
Writing alerts.channels in obs-beacond.yaml, even as channels: [], makes
the file the place for them, and the web interface shows them read-only. In
the file, secrets are always files of their own, never inline:
alerts:
public_url: https://obs.example.org
channels:
- id: ntfy
type: ntfy
min: serious
topic_file: /etc/obs-beacon/ntfy-topic
# server: https://ntfy.example.org
# token_file: /etc/obs-beacon/ntfy-token
- id: oncall
type: pagerduty
min: critical
routing_key_file: /etc/obs-beacon/pagerduty-key
- id: chat
type: discord
webhook_file: /etc/obs-beacon/discord-webhook
mention_critical: true
- id: hook
type: webhook
url_file: /etc/obs-beacon/webhook-url
secret_file: /etc/obs-beacon/webhook-secret
- id: mail
type: email
smtp: smtp.example.org:587
from: "Cairn OBS <obs@example.org>"
to: [ops@example.org]
password_file: /etc/obs-beacon/smtp-password
Secret files belong to root:obs-beacon, mode 0640. Secrets never appear
in obs-beacond's logs or errors: a failing channel is named by its id.