Alert notifications
Notifications go out within about a minute of a HARD change, through every
channel your organisation has set up: email, a webhook (signed JSON, Slack,
Microsoft Teams or PagerDuty), and Jira. Channels belong to the organisation
(one contact list per organisation) and are set by an admin on the
Notifications page (Configure › Notifications in the sidebar). The
Channels tab of the Alerts page shows them read-only. 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?
Section titled “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 |
ESCALATION | An escalation level is told about an unhandled problem (email only) |
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
Section titled “Email contacts”Enter up to 20 addresses under Email contacts, one per line, and click
Save email 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:…).
Why isn’t an address getting email?
Section titled “Why isn’t an address getting email?”An address is mailed only once it has confirmed, unless it is an organisation member’s sign-in email. Saving any other address sends it one confirmation email with a link to a Confirm your address page (Confirm or Decline); the link is valid for 7 days. Each address on the list shows its status, and an admin can Resend a confirmation (at most one a day per address, and 20 a day per organisation). The same applies to the addresses of escalation levels and the digest.
| Status | Mailed? |
|---|---|
member | Yes: an organisation member’s sign-in email |
confirmed | Yes |
awaiting confirmation | No: a confirmation was sent and not answered yet |
confirmation expired | No: the link expired after 7 days. Resend it |
declined | No. Remove the address and add it again to ask once more |
not confirmed | No: no confirmation went out (the daily limit). Resend it |
Unconfirmed addresses are skipped and named in the delivery log; the others are still mailed.
Can email go out only during working hours?
Section titled “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
Section titled “Webhook”One webhook per organisation, in one of four formats. Pick a Format,
enter the URL (or, for PagerDuty, the Region and Integration key),
and click Add webhook (Save webhook once one exists). The URL must be
https on a public host, with no credentials in it. It is stored encrypted;
afterwards only its start is shown. Remove deletes it.
| Format | What it sends |
|---|---|
| Signed JSON | One signed JSON POST per run with every notification in it (below) |
| Slack | One message per run to a Slack incoming webhook, worst first |
| Microsoft Teams | One Adaptive Card per run to a Teams Workflows “Post to a channel when a webhook request is received” URL, worst first |
| PagerDuty | Events API v2, one event per notification: a PROBLEM triggers an alert, an acknowledgement here acknowledges it and a recovery resolves it. Flapping notices are not sent. Region is US (events.pagerduty.com) or EU (events.eu.pagerduty.com); the integration key is 32 characters |
A Slack or Teams message shows up to 20 notifications and counts the rest; a PagerDuty run sends at most 50 events. A PagerDuty test send triggers one alert and resolves it at once.
Signed JSON
Section titled “Signed JSON”On the first save SZ-MCP creates a signing secret (whsec_ followed by 64 hex
characters) and shows it once: copy it then. Rotate secret replaces it
(update your receiver at the same time). Only this format has a 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, ruleDescription, runbook, notes, context (see
below) and explanation (see
below).
Every webhook request, in any format, times out after 10 seconds and redirects are not followed. A network error, a 5xx or a 429 response gets one retry straight away; any other 4xx does not.
How do I verify X-SZMCP-Signature?
Section titled “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:
- Read the raw body before parsing it.
- Compute
HMAC-SHA256(secret, timestamp + "." + body)and hex-encode it. - Compare it with the part after
v1=using a constant-time comparison. - 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);}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, unless you change the Site URL: then enter it again |
| 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
Section titled “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]. An organisation can send up to 5 tests an hour.
Recent deliveries on the Notifications page lists each channel’s sends over the last 30 days, with failures and held emails. Deliver notifications, in the page’s Delivery card, is the master switch: with it off, problems are still tracked but nothing is sent.
Escalations
Section titled “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 Notifications page (up to 10 levels):
| 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) |
| 1 to 20 addresses, each confirmed as for email contacts | |
| 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, 5 to 10,080 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.
Can I get a daily or weekly digest?
Section titled “Can I get a daily or weekly digest?”Yes: the Digest card on the Notifications page emails a shift handover on a
schedule. Choose Every day or week (and On which day), At an hour
and a Time zone, add up to 20 addresses (confirmed as for email contacts),
and click Save digest. It lists the problems now, HARD problems since the
last digest, changes, new best-practice findings, certificates and licences
expiring within 30 days, availability and unknown devices. Its subject starts
[SZ-MCP digest]. Send a test sends one now without moving the schedule;
Send the digest turns it off and on; Remove deletes it. The same digest
is on the Reports page. Full page: Shift-handover digest.
What else comes with a problem?
Section titled “What else comes with a problem?”A PROBLEM or ESCALATION notification carries the problem’s context, the rule’s runbook and the site’s notes, gathered when it is sent, with no AI model involved. Acknowledgements carry the runbook and notes too.
- Context: where the device sits, what it hangs off and that upstream’s
state, other current problems nearby, its events in the last 2 hours, changes
on it in the last 24 hours, its metrics against a usual week, and how often
the problem happened in the last 30 days. Claude reads the same with
alerts.context. - Runbook: the rule’s
runbookfield (see Alert rules). - Notes: site notes on the device, what contains it, its location and the
whole organisation, nearest first. Operators and above add them by asking
Claude (
notes.add).
Email and Jira show all three; Slack and Teams show where the device is and the
runbook’s first lines; PagerDuty puts them in the alert’s details; the signed
JSON webhook carries context, runbook and notes. Email and Jira leave
them off recoveries.
What does a notification explain?
Section titled “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.