Buttons on notifications: acknowledge, silence and snooze from the message
- A switch (off by default) under Settings -> Notifications -> Who hears what - ntfy gets buttons (three for one alert, one link for several); phone push gets two buttons handled by the service worker; Gotify, email and the chat webhook get the link as text; escalation messages carry them too - Each link is a signed token for the alerts in that one message only, good for 24 hours, for three actions; opening it changes nothing, only a POST acts; everything is audited as "from a notification link" - Docs updated Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
1 parent
0277126add
commit
aebf3c6ce1
22 files changed
+895
-28
No files matched your search
@@ -395,6 +395,7 @@ How the figures are used is in [MONITORING.md](MONITORING.md).
|
||||
| `GET /metrics` | Prometheus text format | `Authorization: Bearer hlm_m_…` | [PROMETHEUS-GRAFANA.md](PROMETHEUS-GRAFANA.md) |
|
||||
| `GET /api/public/calendar/<token>.ics` | A calendar feed of what is coming up | in the address (a share link) | [HEARTBEATS-AND-CALENDAR.md](HEARTBEATS-AND-CALENDAR.md) |
|
||||
| `GET /api/public/status/<token>`, `/api/public/wall/<token>` | The data behind a shared status page and wall display | in the address (a share link) | Settings → Share links |
|
||||
| `GET /api/alert-actions/<token>`, `POST /api/alert-actions/<token>/<ack\|silence\|snooze>` | The page and the buttons behind a notification | a signed token in the address (24 hours, for the alerts in that message) | [WEBHOOKS.md](WEBHOOKS.md#buttons-on-notifications) |
|
||||
| `GET /health` | Is the app up? | none | answers `{"ok":true}` |
|
||||
|
||||
## Reading the API safely
|
||||
|
||||
@@ -175,6 +175,7 @@ Some addresses are meant for machines and use their own tokens instead of a sess
|
||||
| `/api/v1/…` | scripts, Home Assistant | a *personal API token* (user menu → API tokens) — see [API.md](API.md) |
|
||||
| `/api/heartbeat/<token>` | cron jobs | the heartbeat's own address — see [HEARTBEATS-AND-CALENDAR.md](HEARTBEATS-AND-CALENDAR.md) |
|
||||
| `/api/public/…` | status pages, the wall display, the calendar feed | a *share link* (Settings → Share links) |
|
||||
| `/api/alert-actions/<token>…` | the buttons and links on a notification | a signed token for the alerts in one message, valid 24 hours — see [WEBHOOKS.md](WEBHOOKS.md#buttons-on-notifications) |
|
||||
| `/health` | container health checks | none (answers `{"ok":true}`) |
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
@@ -22,6 +22,7 @@ here, and they are easy to mix up:
|
||||
- [A small receiver](#a-small-receiver)
|
||||
- [Home Assistant and n8n](#home-assistant-and-n8n)
|
||||
- [The notification webhook](#the-notification-webhook)
|
||||
- [Buttons on notifications](#buttons-on-notifications)
|
||||
- [Troubleshooting](#troubleshooting)
|
||||
|
||||
## Event webhooks
|
||||
@@ -270,6 +271,33 @@ X-Webhook-Secret: <the secret> (only if one is set)
|
||||
- The secret is stored encrypted when `CREDENTIALS_ENCRYPTION_KEY` is set. The **Send test** button on the channel sends a one-off message through that channel only.
|
||||
- Which messages exist, and when each is sent, is in [NOTIFICATIONS.md](../NOTIFICATIONS.md).
|
||||
|
||||
## Buttons on notifications
|
||||
|
||||
A notification can carry buttons that act on the alert it is about, from the phone's lock screen, without signing in: **Acknowledge**, **Silence for an hour** and **Snooze until tomorrow at 09:00**. An administrator switches
|
||||
it on under **Settings → Notifications → Who hears what → Buttons on notifications**; it is off until then, and off means no link works. How each channel shows them is in [NOTIFICATIONS.md](../NOTIFICATIONS.md#buttons-on-notifications).
|
||||
|
||||
The addresses behind them, for anything that wants to build on it:
|
||||
|
||||
```
|
||||
GET /api/alert-actions/<token> a page listing the alerts with a button for each action — opening it changes nothing
|
||||
POST /api/alert-actions/<token>/ack acknowledge ("Acknowledged from a notification", until the alert is gone)
|
||||
POST /api/alert-actions/<token>/silence start an hour of maintenance on what the alert is about (only if it is about something a window can silence)
|
||||
POST /api/alert-actions/<token>/snooze snooze until tomorrow 09:00 in the notification time zone
|
||||
add ?key=<alert key> (or a form field "key") when the token is for more than one alert
|
||||
```
|
||||
|
||||
```json
|
||||
{ "ok": true, "message": "Acknowledged." }
|
||||
```
|
||||
|
||||
- **The token is the access.** It is signed (HMAC-SHA256, with a key derived from `SESSION_SECRET`), is for the **alerts named in it only** (the alert keys of that one message, up to 20), and **ends after 24 hours**. Nothing
|
||||
is stored. A forged, altered or ended link is `404`/`410`. A `key` that is not in the token is `400`; an alert that has cleared is `404` ("it has cleared"); a silence for something with nothing to silence it with is `409`.
|
||||
- **It can do these three things and nothing else** — no reading, no settings, no other alert. Everything it does is in the audit log, said to be done *from a notification link*, with the IP address it came from.
|
||||
- **A POST from a browser form gets a page back; anything else gets JSON.** `GET` never acts, so a link preview, a chat unfurl or a mail scanner cannot press a button. Limited to 60 requests a minute from one address.
|
||||
- **Anyone who can read the notification can use its buttons** for the 24 hours. That is the trade for not having to sign in: keep the ntfy topic private (a self-hosted ntfy, or a topic with a password), do not point this at a public
|
||||
topic, and remember the link is in an email's text. Changing `SESSION_SECRET` or switching the setting off ends every link at once.
|
||||
- The links are built from `APP_BASE_URL`, so it has to be an address your phone can open.
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
| Symptom | Cause |
|
||||
|
||||
Reference in new issue
Block a user