lanowl

Reference

Webhook

Besides Telegram (and MQTT, where every message is also published), lanowl can send every alert as one HTTP POST of JSON to an address of your own: an Apprise server, ntfy, n8n, Home Assistant, a gateway to Matrix or Slack. It works with Telegram not set up.

Switch it on

webhook:
  enabled: true
  format: "generic"           # generic, apprise, ntfy, or template

The address goes in secrets.yaml, not here, because it often carries a key (a path or a query a stranger could post with):

tokens:
  webhook_url: "https://hooks.example.org/lanowl/…"
  webhook: "…"                # a bearer token, only if the receiver wants one

Or in the environment: LANOWL_WEBHOOK_URL and LANOWL_WEBHOOK_TOKEN (each also as _FILE). Settings → Secrets sets and replaces both from the dashboard, as it does the Telegram token. They are read again at every message, so a new one needs no restart; the settings in config.yaml do. Set the address first: lanowl --check, and so Settings, calls a webhook that is on with no address a problem.

Settings → Webhook has a Send test notification button and a line that says what the last delivery did ("Delivered 14:03 · 0 waiting", "Failing since 14:03: HTTP 502 · 4 waiting · next try 14:05", "Not set: no address in secrets.yaml"). The test sends one message straight away, with the settings and secrets as saved, whether the webhook is on or not, so you can try it before you switch it on. lanowl --check shows one line, "Webhook: on · generic · to hooks.example.org", and sends nothing.

The address and the token are never in the log, Telegram, MQTT, the dashboard or what the owl reads. The log names the receiver's host and nothing more of the address.

What it sends, and when

It gets what Telegram gets, no more: the same incidents (one message per incident, a recovery when it is over), the same digests, the same opt-ins: a new device still needs discovery.notify_new_devices. --no-telegram mutes it too. events and min_severity can only narrow that down. The dashboard says where each message went: on the Timeline, under Messages, it reads Telegram, Webhook, both, or Not sent.

One POST per Telegram message. A message about several devices is one POST: each device has a line in its message ("NAS (192.168.10.5): unreachable (icmp)") and an entry in its incidents.

events picks the kinds of message:

Kind What On by default
down A device or service down, and the reminder that it still is ✓
recovery It is back. A problem only the digest had named is told back only with digest on too: otherwise the webhook never heard of it ✓
wan The internet: no internet, back, on the backup line ✓
security The security review, a login from an unknown address, failed logins, a connection flood, a locked dashboard login, the owl's shell not isolated ✓
new_device A device never seen on the network ✓
logs A host's or a device's own log, the router's log, a port slower or back ✓
diagnosis The owl's diagnosis of an incident (below) ✓
proposal An action the owl or the audit proposes, waiting for your yes. A POST has no buttons, so you answer it on the dashboard ✓
digest The digest and the week in review
maintenance Updates, backups, lanowl's own updates, an action you approved on the dashboard, a muted port
other Pause and resume, the owl switched on or off, a Settings change, the dashboard's setup, an address change, the dashboard closed until a password is set

min_severity (info, warning, high, critical; default info) drops what is less bad than that. A recovery counts as info, and so does a proposal: above info, proposals are left out too. A diagnosis has its incident's severity.

The generic body

{
  "sender": "lanowl",
  "title": "NAS offline",
  "message": "NAS (192.168.10.5)\nunreachable (icmp)",
  "severity": "critical",
  "event_id": "5c0f6d0a9e4b4f5c8a1d2b7e3f9a6c41",
  "event_type": "device_down",
  "category": "down",
  "timestamp": "2026-11-17T14:02:27+01:00",
  "incident_id": "9b1e4c7a2d6f3e80",
  "device": {"name": "NAS", "ip": "192.168.10.5", "mac": "AA:BB:CC:00:00:05"},
  "incidents": [
    {"incident_id": "9b1e4c7a2d6f3e80", "event_type": "device_down", "severity": "critical",
     "device": {"name": "NAS", "ip": "192.168.10.5"}}
  ]
}
Field What
title, message Plain text: Telegram's formatting is gone, its lines are kept. The title is the first line without its emoji and time; for a device, "NAS offline", "NAS still offline", "NAS back online", "3 devices offline".
severity critical, high, medium, low or info (the table below).
event_id Unique to the message, and the same on every retry: a receiver can drop a duplicate by it.
event_type device_down, device_still_down, device_up, wan_down, wan_up, wan_warning, log_alert, security_alert, new_device, diagnosis, digest, weekly, maintenance, proposal, notice, test.
category The kind of message, as events names it.
timestamp When it happened, ISO 8601 with the offset, not when it was delivered.
incident_id Only when the message is about exactly one incident. An alert and its recovery have the same one.
device Only when the message is about exactly one device: name, ip, and mac when lanowl knows it.
incidents Every incident the message covers: its incident_id, event_type, severity and device.
in_reply_to Only on a diagnosis: the event_id of the message it follows.

A field the message does not have is left out, not null.

Severity

lanowl generic apprise type ntfy priority
critical critical failure 5
high high failure 4
warning medium warning 3
info low info 2
recovery info success 3

The owl's diagnosis

Telegram gets the owl's diagnosis of a new critical incident a few minutes later, edited into the alert. A POST cannot be edited, so the webhook gets a second one: event_type: "diagnosis", the same incident_id (or incidents), and in_reply_to, the event_id of the message that announced it. One follow-up for each message that announced an incident. It needs no Telegram, and is not sent for an incident the webhook was not told about (filtered out, or announced before lanowl last started).

The other formats

apprise, for an Apprise server's JSON notification:

{"version": "1.0", "title": "NAS offline", "message": "NAS (192.168.10.5)\nunreachable (icmp)",
 "type": "failure", "sender": "lanowl"}

ntfy: the address is the one you would open, https://ntfy.example.org/lanowl. lanowl posts to the server's root with the topic in the body, as ntfy's JSON publish wants:

{"topic": "lanowl", "title": "NAS offline", "message": "NAS (192.168.10.5)\nunreachable (icmp)",
 "priority": 5, "tags": ["rotating_light"]}

The tags are rotating_light (critical), warning (high, warning), information_source (info) and white_check_mark (recovery). A token in tokens.webhook is sent as Authorization: Bearer …, which is how ntfy takes its access tokens.

template: your own JSON, for a receiver none of the others fits. Every string value may hold {name} placeholders:

webhook:
  format: "template"
  template:
    text: "{title}: {message}"
    severity: "{severity}"
    devices: "{incidents}"
Name What
title, message As above
severity lanowl's own word: critical, high, warning, info or recovery
event_id, event_type, category, timestamp As above
incident_id, in_reply_to As above; empty when there is none
device, ip, mac The one device the message is about; empty otherwise
incidents The list of incidents

A value that is only a placeholder takes the value as it is, so "{incidents}" is the list. Inside a longer string a list is written as JSON. A name lanowl does not know is left as written. Only {name} is filled in: nothing else in a string is read as anything.

Headers

Content-Type: application/json and User-Agent: lanowl/<version>, then what headers adds (for a header that is not secret), then Authorization: Bearer … if tokens.webhook is set. verify_tls: false is for a gateway with a self-signed certificate.

When the receiver does not answer

Each message is tried up to three times, two seconds and then four apart, each with 10 seconds to answer. A message that still has not been taken waits at the head of its queue and is tried again every minute; the ones behind it wait too, so they arrive in order.

Answer What lanowl does
2xx Delivered.
408, 429, 5xx, no answer, no connection Tried again.
Any other 4xx The receiver refused that message: dropped, with a line in the log and in the status.
A redirect Not followed: it would carry the token to another host. Dropped like a refusal.

The queue is a file (webhook.queue_file, in /state): what waited survives a restart. A message older than 24 hours is dropped, and at most 200 are kept, the oldest first to go. Nothing waits for the internet: unlike Telegram, the receiver is often on your own network, so a message goes out during an outage. Nothing on the sweep, Telegram or MQTT ever waits for the receiver either.

Edit this page on GitHub.