Alerts & notifications

Webhooks, Pushover, push notifications, delivery rules and every event type.

Everything that happens in the hub becomes an event: alerts (something needs attention) and audit entries (who did what). Events are kept in the log under Automation → Alerts & Activity, and sent to wherever you choose.

Where alerts can go

Adding a webhook

1. Alerts & Activity → Webhooks → + Add webhookPick the type and paste its URL or keys.
2. Choose what it receivesA minimum severity (info, warning, critical), and an event list: * for everything, exact names, or prefixes like container.* or security.*.
3. Testsends a test event so you can see how it looks.

Pushover in detail

1. Create an applicationat pushover.net/apps to get an API token.
2. Copy your user key(or a group key) from the Pushover dashboard.
3. Add the webhookchoose Pushover and enter both. Optionally pick a sound and a single device, and tick emergency to make critical alerts repeat every minute (for up to an hour) until acknowledged in the Pushover app.

Alternatively, use a Pushover incoming webhook URL (https://api.pushover.net/1/webhooks/….json). No keys are needed, but you must map the fields in Pushover (Title {{title}}, Body {{message}}, URL {{url}}, URL title {{url_title}}). Priority, sound and emergency aren't available that way.

iPhone push notifications

Notifications straight to the Homelab Hand app are delivered by Apple, signed with an APNs key from a paid Apple Developer account. If you have one, you can set this up yourself:

1. Create an APNs keydeveloper.apple.com → Certificates, Identifiers & Profiles → Keys → + → Apple Push Notifications service, environment Sandbox & Production. Download the .p8 (it's offered once). Note the Key ID and your Team ID.
2. Add it to the hubAlerts & Activity → iPhone app: paste the Team ID, Key ID and the .p8, then Save.
3. Sign in on the phoneand allow notifications. The phone appears under Devices, where you set its minimum severity.
4. Send test notificationto check it works. Tapping a notification opens Alerts in the app.

Delivery rules

• Severity: a destination gets events at or above its minimum severity that match its event list.
• Cooldown: the same alert isn't re-sent within the cooldown (default 30 minutes).
• Retries: if a destination is briefly unreachable, delivery is retried. If it still fails, a notify.failed entry is written to the event log, so you can see that an alert didn't arrive.
• Muted containers (glob patterns) never alert. Stops done through the hub never count as unexpected.

Event types

The webhook payload

Generic and n8n webhooks receive the full event:

{
  "id": 412, "ts": "2026-10-07T11:25:29+00:00",
  "event_type": "container.unhealthy", "severity": "critical",
  "title": "uptime-kuma is unhealthy on docker-01", "message": "Up 3 days (unhealthy)",
  "source": "docker-01/uptime-kuma",
  "details": { "host_id": 1, "host": "docker-01", "container": "uptime-kuma", "image": "louislam/uptime-kuma:1" }
}

Signing

If you set a secret, the body is signed: X-HTech-Signature: sha256=<hex HMAC-SHA256(secret, body)>. Extra headers can be added per webhook as JSON. To verify in an n8n Code node:

const crypto = require('crypto');
const sig = 'sha256=' + crypto.createHmac('sha256', 'YOUR_SECRET').update(JSON.stringify($json.body)).digest('hex');
return [{ json: { valid: sig === $json.headers['x-htech-signature'] } }];

Sending your own alerts

Anything that can make an HTTP request can push an alert through the hub's destinations with POST /api/events/ingest and a write API token:

curl -X POST https://hub.example.com/api/events/ingest \
  -H "Authorization: Bearer htk_…" -H "Content-Type: application/json" \
  -d '{"title":"Backup job finished","message":"3.2 GB in 4 min","severity":"info","source":"restic"}'