# Alarm Manager onboarding guide

Step-by-step guide for wiring UniFi Network's Alarm Manager to the webhook URLs this integration generates. Pasting the per-category URLs into Alarm Manager is the single highest-friction step of setup; this page covers it in full, plus verification and the failure modes that account for most "webhooks never arrive" reports.

No screenshots are included here - UniFi Network's Alarm Manager UI changes across firmware versions faster than screenshots stay accurate. Every step below uses an exact textual navigation path instead.

## Where the webhook URLs come from

Each enabled alert category gets its own webhook URL, generated by Home Assistant (not by the UniFi controller) when you finish the config flow:

- **Initial setup:** shown on the "Webhook URLs" screen, the last step before clicking Submit.
- **Any time after setup:** **Settings > Devices & Services > UniFi Alerts > Configure** reopens the options flow and redisplays the current URLs on its own finish step.

Each URL has the form `<home-assistant-url>/api/webhook/<webhook-id>` and no longer embeds the bearer secret (breaking change, issue #176). The "Webhook URLs" screen also shows the secret separately - use it to set an `Authorization: Bearer <secret>` header on each alarm's webhook action, which is the preferred authentication method (see "401 after a secret rotation" below). Alarm Manager versions with no custom-header option can instead append `?token=<secret>` to the URL; this legacy form still works but is deprecated and will be removed no earlier than v3.0.0.

The category list and its exact labels (from `strings.json`):

| Category | Label shown in the config flow |
|---|---|
| `network_device` | Network: Device offline/online |
| `network_wan` | Network: WAN offline/latency |
| `network_client` | Network: Client connect/disconnect |
| `security_threat` | Security: Threat / IDS detected |
| `security_honeypot` | Security: Honeypot triggered |
| `security_firewall` | Security: Firewall block |
| `power` | Power: PoE / power loss |

Only categories you enabled in the "Configure Alert Categories" step get a URL. There is no URL for a disabled category.

## Creating the Alarm Manager rules

Do this once per enabled category, in UniFi Network's own admin UI:

1. Go to **Settings > Notifications > Alarm Manager**.
2. Click **Create Alarm**.
3. Set the trigger that matches the category (see the trigger reference table in the README's Setup section for the exact trigger name per category - Security categories share a single "Security" trigger).
4. Set the scope (specific devices, or network-wide).
5. Under **Action**, choose **Webhook > Custom Webhook > POST**.
6. Paste the webhook URL for that category from the Home Assistant "Webhook URLs" screen.
7. In the alarm's Advanced Settings, add a custom header named `Authorization` with the value `Bearer <secret>` (the secret is shown on the same "Webhook URLs" screen). If there is no custom-header option, append `?token=<secret>` to the URL instead - see the deprecation note above.
8. Click **Create**.

Repeat for every enabled category. Each category needs its own alarm rule pointing at its own distinct URL - pasting one category's URL into another category's rule means that category's alerts never reach the matching HA entity.

UniFi's **Test Alarm** action (available on a saved alarm) sends a synthetic webhook immediately, which is the fastest way to confirm a single rule is wired correctly before waiting for a real event.

## Verifying delivery

You do not need to wait for a real alert to confirm the wiring works. Each category has a dedicated diagnostic `sensor.*_webhook_health` entity (state: `never_received` / `healthy` / `stale`, with a `last_webhook_at` attribute), and the same value is also available as a `webhook_health` attribute on the category's binary sensor:

- `never_received` - no webhook has ever arrived for this category since the integration was set up (or since the last restart that cleared in-memory state).
- `healthy` - the most recent webhook arrived within the last 7 days (`WEBHOOK_STALE_AFTER_SECONDS`, in `const.py`).
- `stale` - the most recent webhook is older than that 7-day window.

The 7-day window is intentionally generous: some categories (honeypot, threat) legitimately go quiet for long stretches on a well-behaved network, so a short window would flag a healthy setup as broken.

To verify a category after pasting its URL:

1. Fire **Test Alarm** from that category's Alarm Manager rule (or wait for a real event).
2. Check the category's webhook health sensor - it should read `healthy`, with `last_webhook_at` showing a recent UTC timestamp.
3. If it still reads `never_received`, see the failure modes below.

The same `webhook_health` and `last_webhook_at` fields are included in the integration's diagnostics download (device page > **Download diagnostics**), which is the fastest way to check every category at once.

## Common failure modes

### 1. Wrong scheme, host, or port in the generated URL

The webhook URL's scheme and host come from Home Assistant's own configured `external_url` / `internal_url` - this integration does not control or override them. If those are wrong (e.g. HA thinks its own address is an old IP, or `http://` where the controller needs `https://`), the generated webhook URL will be wrong or unreachable from wherever the controller sits on the network.

Fix this in Home Assistant itself: **Settings > System > Network**, not in this integration's config. After correcting HA's URL settings, reopen **Settings > Devices & Services > UniFi Alerts > Configure** to see the corrected URLs, and re-paste them into Alarm Manager.

### 2. `local_only` rejection (remote access or cloud-hosted controllers)

Webhooks are registered with `local_only=True`. Home Assistant only accepts the request if it looks like it originated from the local network. This means:

- **Nabu Casa remote access cannot reach the webhook.** It is not a valid delivery path for Alarm Manager regardless of how the URL is configured.
- **Cloud-hosted or off-site UniFi controllers cannot reach it either**, for the same reason.
- A controller reaching HA through a reverse proxy, VPN, or any route that does not look local to HA will have its webhook requests silently rejected - no entry appears in Alarm Manager's own delivery log pointing at HA, and HA logs will not show a rejected request either, since `local_only` is enforced before the request reaches this integration's handler.

There is no workaround in this integration's configuration - the UniFi controller and Home Assistant need to share a local network path for webhook delivery to work. If this is not possible, rely on the REST polling path (open-count sensors) as a backstop; it works over any reachable network path.

### 3. 401 after a secret rotation

Rotating the webhook bearer secret (the **Regenerate webhook secret** option in the options flow) invalidates every `Authorization` header and legacy `?token=` value previously configured in Alarm Manager. Every request using the old secret is rejected with HTTP 401.

Home Assistant raises a `webhook_secret_rotated` repair issue in **Settings > Repairs** when this happens. It clears itself automatically once a valid webhook is received on the new secret.

Fix: open **Settings > Devices & Services > UniFi Alerts > Configure**, copy the new secret from the finish step, and update the `Authorization` header (or re-paste the `?token=` URL) for each category in **Settings > Notifications > Alarm Manager**. A single category left with its old secret will keep 401-ing even after the others are fixed.

### 4. Still using the legacy `?token=` query parameter

Home Assistant raises a `webhook_legacy_query_auth` repair issue in **Settings > Repairs** the first time a webhook authenticates via `?token=` rather than the `Authorization` header. This is informational, not an error - the query parameter still works - but it is deprecated and will be removed no earlier than v3.0.0.

Fix: add an `Authorization: Bearer <secret>` header to the alarm's webhook action under Advanced Settings and drop the `?token=` query string from the URL. The repair issue clears automatically once a header-authenticated webhook is received for that entry.

### 5. URLs changed after an upgrade

Older versions of this integration did not assign a unique suffix to webhook IDs. Upgrading past that point changes every category's webhook URL, and the old URLs already in Alarm Manager stop working. Home Assistant raises a `webhook_urls_changed` repair issue in **Settings > Repairs** describing this and pointing at the fix.

Remediation is identical to a secret rotation: re-copy every category's URL from **Settings > Devices & Services > UniFi Alerts > Configure** and re-paste it into the matching Alarm Manager rule. Delivery does not resume until every category's URL is updated.

## Related documentation

- [`docs/TROUBLESHOOTING.md`](TROUBLESHOOTING.md) - deeper diagnostics for webhooks that never arrive, including a controller-side `curl` test that isolates network reachability from HA configuration.
- [`docs/UNIFI.md`](UNIFI.md) - UniFi API reference, including the alarm payload shape referenced by `webhook_health`.
- The README's Setup section has the full Alarm Manager trigger reference table (which UniFi trigger type maps to which category).