docs
cairnobs.org Demo Source
Esc

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.

2 min read

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
Email 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.