docs(notifications): describe what the webhook sends and Gotify setup

The outbound payload was documented nowhere. The webhook section now shows the generic body and the Gotify body as the Test button sends them, what each field carries, and how to point the webhook at Gotify: a URL ending in /message, the application token in an X-Gotify-Key header, and the Gotify format.

Refs #947
This commit is contained in:
Marc-André Bombeck committed 2026-09-13 14:19:48 +02:00
1 parent fafb5cdc08
commit e788b53be0
1 file changed
+67
+67
View File
@@ -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