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:
bobbanandClaude Sonnet 5.5 committed 2026-10-21 20:42:04 +02:00
1 parent 0277126add
commit aebf3c6ce1
22 files changed
+895 -28

No files matched your search

+28
View File
@@ -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 |