Initial commit
This commit is contained in:
siliconsolder committed
commit
38c24fc9dc
166 files changed
+22002
No files matched your search
@@ -0,0 +1,203 @@
|
||||
# Integration examples
|
||||
|
||||
Concrete configuration for the services named in the original spec. All of
|
||||
these publish through the LAN ingestion listener (`:8081`), never the
|
||||
public URL — see
|
||||
[docs/phase1/01-architecture.md](phase1/01-architecture.md) for why the two
|
||||
are kept separate.
|
||||
|
||||
Every example needs a token first: Settings → Admin → API Tokens → Create
|
||||
token. Store the `nzr_...` value as a secret in whatever the integration
|
||||
uses for secrets (Home Assistant's `secrets.yaml`, Seerr's environment
|
||||
variables, etc.) — never commit it to a config repo in plain text.
|
||||
|
||||
## Home Assistant
|
||||
|
||||
### Replacing `ntfy.publish`
|
||||
|
||||
If you're currently using the `ntfy` integration:
|
||||
|
||||
```yaml
|
||||
# Old
|
||||
action: ntfy.publish
|
||||
data:
|
||||
title: "🏠 {{ trigger.to_state.attributes.friendly_name }}"
|
||||
message: "Window opened"
|
||||
target: homeassistant
|
||||
```
|
||||
|
||||
Add a REST command pointing at Notizarr instead:
|
||||
|
||||
```yaml
|
||||
# configuration.yaml
|
||||
rest_command:
|
||||
notizarr:
|
||||
url: "http://<lan-ip>:8081/api/v1/notifications"
|
||||
method: POST
|
||||
headers:
|
||||
Authorization: !secret notizarr_token
|
||||
Content-Type: "application/json"
|
||||
payload: >
|
||||
{
|
||||
"topic": "{{ topic }}",
|
||||
"title": "{{ title }}",
|
||||
"message": "{{ message }}"
|
||||
}
|
||||
```
|
||||
|
||||
```yaml
|
||||
# secrets.yaml
|
||||
# Note: the secret holds the FULL header value including "Bearer " — a
|
||||
# YAML !secret tag must be the entire value of a key, it can't be embedded
|
||||
# inside a larger string like "Bearer !secret notizarr_token" (that would
|
||||
# be treated as the literal text "!secret notizarr_token", not resolved,
|
||||
# and Notizarr would correctly reject it as an invalid token).
|
||||
notizarr_token: "Bearer nzr_your_token_here"
|
||||
```
|
||||
|
||||
Then call it wherever you used `ntfy.publish`:
|
||||
|
||||
```yaml
|
||||
action: rest_command.notizarr
|
||||
data:
|
||||
topic: homeassistant
|
||||
title: "🏠 Home"
|
||||
message: "Office window is open, don't forget to close it"
|
||||
```
|
||||
|
||||
### As part of an automation
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
- alias: "Notify on window open"
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: binary_sensor.office_window
|
||||
to: "on"
|
||||
action:
|
||||
- action: rest_command.notizarr
|
||||
data:
|
||||
topic: homeassistant
|
||||
title: "🏠 Office window"
|
||||
message: "The office window was just opened"
|
||||
```
|
||||
|
||||
### Silencing specific automations (same topic, no push)
|
||||
|
||||
If some automations are just for the log/history and shouldn't buzz your
|
||||
phone, set `priority: min` (or `1`) on that call — Notizarr still stores it
|
||||
and shows it in the topic like normal, it just skips the push step. Nothing
|
||||
else needs to change, so it stays in the same topic as everything else:
|
||||
|
||||
```yaml
|
||||
automation:
|
||||
- alias: "Log robot vacuum finished (no push)"
|
||||
trigger:
|
||||
- platform: state
|
||||
entity_id: vacuum.living_room
|
||||
to: "docked"
|
||||
action:
|
||||
- action: rest_command.notizarr
|
||||
data:
|
||||
topic: homeassistant
|
||||
title: "🤖 Robot vacuum"
|
||||
message: "Finished cleaning and docked"
|
||||
priority: min
|
||||
```
|
||||
|
||||
The accepted values are the same ntfy uses: `min`/`low`/`default`/`high`/`urgent`,
|
||||
or the numbers `1`-`5` — only `min`/`1` currently changes behavior (no push);
|
||||
the rest are accepted and stored but don't yet affect delivery. Add
|
||||
`priority: "{{ priority }}"` to the shared `rest_command.notizarr` payload
|
||||
(see above) if you want to set it per-call via a template variable instead
|
||||
of hardcoding it in every automation.
|
||||
|
||||
### Deduplicating repeated triggers
|
||||
|
||||
If an automation can fire repeatedly for the same event within a short
|
||||
window (flapping sensors, retried API calls), pass a `deduplication_key` so
|
||||
repeats increment `occurrence_count` in Notizarr's history instead of
|
||||
flooding the topic:
|
||||
|
||||
```yaml
|
||||
rest_command:
|
||||
notizarr:
|
||||
url: "http://<lan-ip>:8081/api/v1/notifications"
|
||||
method: POST
|
||||
headers:
|
||||
Authorization: !secret notizarr_token
|
||||
Content-Type: "application/json"
|
||||
payload: >
|
||||
{
|
||||
"topic": "{{ topic }}",
|
||||
"title": "{{ title }}",
|
||||
"message": "{{ message }}",
|
||||
"deduplication_key": "{{ dedup_key }}"
|
||||
}
|
||||
```
|
||||
|
||||
## Seerr (Overseerr/Jellyseerr)
|
||||
|
||||
Seerr supports generic webhook notification agents. In Settings →
|
||||
Notifications → Webhook:
|
||||
|
||||
- **Webhook URL**: `http://<lan-ip>:8081/api/v1/webhook/seerr`
|
||||
- **Authorization Header**: `Bearer nzr_your_token_here`
|
||||
- **JSON Payload**: Seerr's default webhook payload doesn't match
|
||||
Notizarr's webhook shape (`{topic, title, message, url?}`) out of the box.
|
||||
Use Seerr's payload template editor to produce:
|
||||
|
||||
```json
|
||||
{
|
||||
"topic": "seerr",
|
||||
"title": "{{event}}",
|
||||
"message": "{{subject}} - {{message}}",
|
||||
"url": "{{media.link}}"
|
||||
}
|
||||
```
|
||||
|
||||
Adjust the field names to whatever Seerr's template variables actually
|
||||
expose in your version — check Seerr's webhook test payload if the
|
||||
variables above don't match.
|
||||
|
||||
## Uptime Kuma
|
||||
|
||||
Uptime Kuma's generic Webhook notification type works the same way:
|
||||
|
||||
1. Settings → Notifications → Add New Notification → Webhook.
|
||||
2. **Post URL**: `http://<lan-ip>:8081/api/v1/webhook/uptimekuma`
|
||||
3. **Content Type**: `application/json`
|
||||
4. Uptime Kuma doesn't let you fully remap its payload shape in the UI, so
|
||||
the simplest reliable option is Uptime Kuma's **ntfy** notification type
|
||||
instead of its generic webhook — point it at Notizarr's ntfy-compat
|
||||
endpoint:
|
||||
- **Server URL**: `http://<lan-ip>:8081`
|
||||
- **Topic**: `uptimekuma`
|
||||
- **Authorization**: Bearer token, `nzr_your_token_here`
|
||||
- **Priority**: whatever Uptime Kuma offers — accepted and ignored, see
|
||||
[docs/migration-ntfy.md](migration-ntfy.md#whats-different).
|
||||
|
||||
## Any other service with a generic webhook
|
||||
|
||||
The pattern is the same everywhere:
|
||||
|
||||
```bash
|
||||
curl -X POST http://<lan-ip>:8081/api/v1/webhook/<source-name> \
|
||||
-H "Authorization: Bearer nzr_your_token_here" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"topic": "your-topic-slug",
|
||||
"title": "Notification title",
|
||||
"message": "Notification body",
|
||||
"url": "https://optional-link.example.com"
|
||||
}'
|
||||
```
|
||||
|
||||
`<source-name>` in the URL becomes the notification's `source` field —
|
||||
pick something recognizable (`gitea`, `sonarr`, `radarr`, ...). If the
|
||||
service can't be configured to send exactly this JSON shape, check whether
|
||||
it has an "ntfy" notification type instead — Notizarr's ntfy-compat
|
||||
endpoint (`POST /:topic`, see
|
||||
[docs/migration-ntfy.md](migration-ntfy.md)) accepts a wider range of input
|
||||
shapes (plain text, headers, query params) and is often the easier target
|
||||
for apps that weren't built with Notizarr specifically in mind.
|
||||
Reference in new issue
Block a user