Notizarr/docs/home-assistant.md

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