diff --git a/docs/self-hosting/notifications.md b/docs/self-hosting/notifications.md index a3dd06de1..e0416e86c 100644 --- a/docs/self-hosting/notifications.md +++ b/docs/self-hosting/notifications.md @@ -207,6 +207,73 @@ Home Assistant on your own network needs the operator grant described in the next section. The webhook carries the event's urgency flag so you can route urgent events differently. +### What the webhook sends + +Every event is one `POST` with `Content-Type: application/json` and the +one header you configured. It goes to the URL exactly as you saved it: +nothing is added to the path or the query. The body depends on the +**Payload format** you choose on the card. The examples below are what the +Test button sends. + +**Generic JSON** is the default, and what every webhook saved before the +choice existed keeps sending: + +```json +{ + "title": "HealthLog Test", + "message": "HealthLog: Connection successful! Webhook notifications are active.", + "eventType": "SYSTEM_ALERT", + "priority": "default" +} +``` + +- `title` and `message` are plain text. HTML tags are stripped, and routine + reminders lose their decorative emoji. +- `eventType` is the event name, for routing rules. With discreet cycle + notifications on, a cycle event arrives as `reminder`, and its title and + message are masked as they are on every other channel. +- `priority` is a word: `urgent` for an event flagged urgent, `high` for + medication reminders, `default` for everything else. + +**Gotify** sends the body Gotify's `POST /message` endpoint expects: + +```json +{ + "title": "HealthLog Test", + "message": "HealthLog: Connection successful! Webhook notifications are active.", + "priority": 5, + "extras": { + "client::display": { "contentType": "text/plain" }, + "healthlog::event": { "type": "SYSTEM_ALERT" } + } +} +``` + +- `priority` is an integer: `5` for most events, `8` for medication + reminders, `10` for urgent events. The Gotify Android app plays a sound + from 4 and shows a heads-up banner from 8, so routine events are audible + and reminders pop up on screen. +- `extras` tells Gotify clients to show the message as plain text and + carries the event name, which is `reminder` for a discreet cycle event. + +The generic body does not work with Gotify. Gotify reads `priority` as a +number, so the word `default` makes it answer `400 Bad Request`. + +### Sending to Gotify + +1. In Gotify, create an application and copy its token. +2. On the Webhook card, set **URL** to your Gotify address ending in + `/message`, for example `https://gotify.example.com/message`. +3. Set **Header name** to `X-Gotify-Key` and **Header value** to the + application token. Gotify also accepts the token as `?token=` on the URL, + but in a header it stays out of proxy access logs. +4. Set **Payload format** to **Gotify**, save, and press Test. + +If the test fails, the card shows the status Gotify answered and, when it is +short, Gotify's own error text. A `401` means the token is wrong. A `400` +means Gotify could not read the body; check that the format is set to +Gotify. A Gotify on your own network also needs the operator grant below. + ## Notification targets on a private network Every webhook and ntfy target is resolved at send time and refused when