Alert notifications

Notifications go out within about a minute of a HARD change, through every channel your organisation has set up: email, a signed webhook, and Jira. Channels belong to the organisation (one contact list per organisation) and are set by an admin on the dashboard’s Alerts card, under Notifications. Claude can read them with alerts.channels() but cannot change them.

Until a channel is set, problems still appear on the Alerts page, but nobody is told.

What gets notified?

Notification	Sent when
PROBLEM	A problem becomes HARD, changes state while HARD, repeats (renotify), or is released from downtime, acknowledgement, flapping or an upstream outage
RECOVERY	A HARD problem that was notified returns to OK
ACKNOWLEDGEMENT	Someone acknowledges a problem, with their comment
FLAPPINGSTART / FLAPPINGSTOP	An instance starts or stops flapping

Each channel is tried at most once per notification. A failed channel is logged and not retried on the next run, so one broken webhook cannot hold up the others or repeat pages. Notifications that are more than 30 minutes old when first picked up (for example, when a channel was only just added) are skipped rather than sent late.

Email contacts

Enter up to 20 addresses under Email contacts, one per line, and click Save contacts. Mail comes from alerts@mail.lanpulse.com; several notifications in the same minute arrive as one digest, worst first. The subject of a single notification reads like [SZ-MCP] PROBLEM: ap-offline is CRITICAL on Lobby-AP-3 (ap:…).

Can email go out only during working hours?

Yes. Tick Email only during certain hours and choose the days, a From and to time, and a Time zone (an IANA name such as Europe/London). An end before the start runs past midnight, so 18:00 to 08:00 covers nights.

Outside those hours email is held; the webhook and Jira still get everything. When the hours start, the contacts get one catch-up email of the problems that went HARD while email was held and are still open and unhandled (not acknowledged, in downtime, unreachable or flapping). Problems that recovered in between are not repeated. A test send ignores the hours. For someone to be called out of hours, use an escalation.

Webhook

Enter a Webhook URL and save. The URL must be https on a public host, with no credentials in it. On the first save SZ-MCP creates a signing secret (whsec_ followed by 64 hex characters) and shows it once: copy it then. Rotate webhook secret replaces it (update your receiver at the same time), and Remove webhook deletes the URL and secret.

Each delivery run sends one JSON POST with every notification in it:

{
  "type": "sz-mcp.alerts",
  "version": 1,
  "org": { "id": "…", "name": "…" },
  "sentAt": "2026-09-26T14:02:00Z",
  "notifications": [
    {
      "notification": "PROBLEM",
      "rule": "ap-offline",
      "instance": "…",
      "entity": "…",
      "name": "Lobby-AP-3",
      "state": "CRITICAL",
      "type": "HARD",
      "output": "…",
      "at": 1790431320000,
      "summary": "PROBLEM: ap-offline is CRITICAL on Lobby-AP-3 (…)"
    }
  ]
}

A notification can also carry value, prev (the previous state), labels (the rule’s), detail, and explanation (see below).

The request times out after 10 seconds and redirects are not followed. A network error or a 5xx response gets one retry straight away; a 4xx does not.

How do I verify X-SZMCP-Signature?

Every POST carries two headers:

Header	Value
X-SZMCP-Timestamp	Unix time in seconds when it was sent
X-SZMCP-Signature	v1= followed by the lowercase hex HMAC-SHA256 of <timestamp>.<body>

The HMAC key is the whole secret string as shown, whsec_ prefix included, as UTF-8 bytes. The body is the raw request body, exactly as received. To verify:

1. Read the raw body before parsing it.
2. Compute HMAC-SHA256(secret, timestamp + "." + body) and hex-encode it.
3. Compare it with the part after v1= using a constant-time comparison.
4. Reject timestamps too far from your clock (for example, more than 5 minutes), so a captured request can’t be replayed.

In Node.js:

import { createHmac, timingSafeEqual } from 'node:crypto';

function verify(rawBody, headers, secret) {
  const ts = headers['x-szmcp-timestamp'];
  const sig = headers['x-szmcp-signature'] ?? '';
  if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
  const expected = 'v1=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  return a.length === b.length && timingSafeEqual(a, b);
}

Jira

Click Connect Jira and choose:

Field	What to enter
Jira	Jira Cloud (atlassian.net) uses an account email and API token; Jira Data Center / Server uses a personal access token
Site URL	e.g. https://yourcompany.atlassian.net (https, public host)
Account email	Cloud only. Use a service account that can only create issues in the project
API token / Personal access token	Write-only: stored encrypted, never shown again. Leave blank when editing to keep it
Project key	e.g. NOC
Issue type	Default Task
Resolve the issue when the problem recovers	On by default
Resolve transition	Optional; by default the first transition to a Done status

Only a HARD CRITICAL problem opens an issue, one per problem, labelled sz-mcp. Later notifications for that problem (acknowledgement, state changes, repeats) are added as comments, and on recovery the issue gets a comment and, if chosen, is moved to done. A WARNING problem never opens an issue. A test send checks the connection (it reports who the token authenticates as) without creating an issue.

Testing and the delivery log

Send a test (admin) sends a made-up WARNING notification through every channel and reports each one as ok or failed with the reason. Test emails are prefixed [SZ-MCP test].

Recent deliveries on the Alerts card lists each channel’s recent sends, failures and held emails. Deliver notifications is the master switch: with it off, problems are still tracked but nothing is sent.

Escalations

An escalation level emails more people when a HARD problem stays unhandled for a while. Unhandled means not acknowledged, not in downtime, not unreachable and not flapping. Add one with Add an escalation level on the Alerts card:

Field	Meaning
Name	e.g. Facilities manager (up to 60 characters)
After (minutes unhandled)	How long the problem must have been HARD in that state, 1 to 10,080 (7 days)
Email	1 to 20 addresses
States	Which states escalate: CRITICAL (default), WARNING, UNKNOWN
Only these rules	Optional list of rule names
Only rules with these labels	Optional, e.g. area=switching
Only during certain hours	Optional days, times and time zone, as for email contacts
Repeat every	Optional, minimum 5 minutes; blank means once
Enabled

A level emails its list once (or at each repeat), only inside its hours, and later tells the same people when the problem is acknowledged or recovers. Escalation emails are prefixed [SZ-MCP escalation] and say which level sent them.

What does a notification explain?

A notification from an event rule carries the SmartZone Alarms and Events Reference Guide’s entry for its code: what the alarm is, what it means, the recommended action, and which event clears it. This comes from a bundled copy of the 7.2.0 guide (186 alarms and 688 events), looked up directly: no AI model is involved in writing notifications. It appears in email, the webhook (explanation: title, meaning, action, clears, source), Jira and escalations; the text in email and Jira leaves it off recoveries.

You can look codes up yourself by asking Claude, which uses alerts.explain: “What does SmartZone alarm 302 mean and what should I do about it?” The guide’s text is general; check the device before acting on it.

Next steps

Monitoring the monitoring Find out when alerting itself stops working: /health/org and the heartbeat.

How alerts work When something becomes HARD, and what suppresses a notification.

Alert rules Rule labels, renotify and the starter pack.