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 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:

# 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:

# 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 }}"
      }

# 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:

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

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:

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:

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:
```
{
  "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:

Settings → Notifications → Add New Notification → Webhook.
Post URL: http://<lan-ip>:8081/api/v1/webhook/uptimekuma
Content Type: application/json
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.

Any other service with a generic webhook

The pattern is the same everywhere:

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) 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.

6.4 KiB Raw Blame History