Event reference
Every event has the same envelope; data depends on type.
| Field |
Type |
Meaning |
id |
string |
The event's ID, the same wherever it is read. Deduplicate on it |
cursor |
string |
Its position where it was read: your organization's log, or the hub's events |
type |
string |
Event type, below |
hub_id |
string |
The hub |
device_id |
integer or null |
The device the event is about |
time |
timestamp |
When it happened, by the hub's clock (the cloud's for hub.*) |
clock_trusted |
boolean or null |
false when the hub stamped it before it knew the time |
data |
object |
Type-specific fields |
Hub
| Type |
data |
hub.offline |
{"reason": "mqtt_keep_alive_timeout"}: the hub has been offline for 30 seconds. time is when it disconnected; reason is AWS IoT's disconnect reason, lowercased, or null. A hub back within 30 seconds records neither this nor hub.online |
hub.online |
{"offline_s": 412}: the hub is back after a hub.offline. offline_s is how long it was offline, in seconds, or null when unknown (its first connection) |
hub.unstable |
{"reasons": ["disconnects"], "disconnects_1h": 4}: the hub's connection became unstable. reasons are disconnects (3 or more unplanned disconnects in an hour, short drops included), packet_loss, retransmits (5 % or more) and latency (a p95 round trip of 2 s or more), as the hub reports them. See hubs |
hub.stable |
{}: every reason has cleared: at most one disconnect in the last hour, and loss, retransmits and latency below half their limits |
hub.network_changed |
{"from": "ethernet", "to": "cellular"}: the hub's status names a different network from the last one it named, ethernet, wifi or cellular, whether it changed while connected or across a reconnect. Recorded by the cloud |
hub.events_skipped |
{"from": 1, "to": 899}: some events could not be delivered. Re-read devices for current state |
hub.alarm_raised, hub.alarm_cleared |
{"alarm": "ZWavePortDown", "description": "…"}: a hub health alarm started or ended. description is for people and can change between firmware versions; read alarm. An alarm standing when the hub starts is raised again. The health alarms that need a person, and their classes, are in Health alarms. NotSecured stands while a lock or garage door that a put-back couldn't confirm hasn't reported locked or closed (see device.not_secured); ZWaveS0Door while a lock or garage door is driven over the older S0 security (see S0) |
hub.condition |
{"code": "InternetUnreached", "active": true}: a cause behind one of the hub's status lights that isn't an alarm began (active true) or ended. LinkWindowSpent: the network being tried didn't come up in its window. InternetUnreached: on the network 2 minutes without reaching the internet. MqttLinkDown: on the internet 2 minutes without connecting to the cloud |
hub.wifi_failover |
{"from": "Lobby", "to": "Lobby-old", "held_s": 900}: the Wi-Fi network from didn't reach the internet, so the hub is moving to to and holds from out for held_s seconds. See Wi-Fi |
network.setup_code_requested |
{"window": "add", "code": "12345-67890-12345-67890-12345-67890-12345", "pin_needed": true, "expires_in_s": 240, "device_id": 21}: a device that joined waits for someone to check its setup code against its label. code is the code's last seven groups; pin_needed asks for its first five digits too. Answer within expires_in_s seconds: see confirming the setup code. device_id when the hub has named it. It can come after network.window_closed |
network.window_closed |
{"window": "add", "outcome": "joined", "device_id": 21}: a pairing (add) or removal (remove) window closed. outcome is joined, removed, cancelled, timeout or failed (with reason). removed with no device_id is usually a device that left another network |
Channels
| Type |
data |
channel.observed |
{"key": "lock", "endpoint": 0, "value": false, "cause": {"source": "keypad", "slot": 3, "credential_id": 12}}: the device reported a value. Sent on every change; for alarm and button channels, on every report, with value {type, event, severity} or {button, event, count}. An alarm whose event is idle means that type cleared, as when a leak sensor dries: current state is in the channels it derives (leak, smoke, co, motion, contact, tamper). cause (Cause) is who or what changed it |
channel.desired |
{"key": "lock", "endpoint": 0, "value": false}: a command asked for a value |
channel.recovered |
{"key": "lock", "endpoint": 0, "value": false, "at": "2026-10-03T14:01:00Z"}: history the device kept while the hub couldn't hear it, such as a lock's own log read back after an outage. at is when the device says it happened, or null. cause (Cause) when the device's record names one. It doesn't change the channel's current value |
A set's outcome is the channel.observed that follows its channel.desired. A move or stop has no channel.desired: where it stops is the next channel.observed.
Devices
| Type |
data |
device.added |
{"name": "Front door", "room": "Entrance", "setup_code_id": "3f2a9c0d1e4b5a67"}; setup_code_id when it joined from a SmartStart code, without the sc_ prefix |
device.updated |
{"name": "Front door", "removed_channels": […]} |
device.available, device.unavailable |
{}: the radio can reach the device again, or no longer can |
device.forgotten |
{"name": "Front door"}: removed from the hub. "reason": "reset_locally" when it was reset at the device and left the network, "forced" when a force removal removed it without exclusion |
device.not_secured |
{"endpoint": 0, "key": "lock", "attempts": 3, "reason": "unconfirmed", "cause": {"source": "automation", "automation": "gym-opens", "run_id": "…", "chain": ["gym-opens"]}}: a put-back to a lock or garage door that didn't secure it. reason is unconfirmed (its attempts went unconfirmed: three for a lock, one for a barrier), not_sent (none of its attempts went out within their span, three minutes for a lock or 90 seconds for a garage door after it fell due, the radio being down, say; the hub still tries it when it can) or forgotten (the device was forgotten, or its channel gone, first). cause (Cause) is its command's: remote for a command's for, automation for a relock, schedule for a schedule. For unconfirmed and not_sent, the hub's health lists NotSecured until the device reports locked or closed, which ends the put-back confirmed, or the device is forgotten |
device.setup_completed |
{"by": "[email protected]", "checks": {…}}: its setup was marked complete |
device.setup_reopened |
{}: put back into setup |
device.setup_test_step |
{"step": 1, "key": "level", "endpoint": 0, "from": 0, "value": 50, "state": "sent"}: a step of its test; state sent or reported; from on the first step |
device.setup_tested |
{"check": "works", "passed": true}: its test, or a ping ("check": "reachable"), finished. A failed test has reason (no_report, send_failed, insecure, unknown_state, crashed, interrupted, unrestored) and, when the hub sent the starting value back, restored |
Put-backs
A put-back is a command's for, an automation's relock, or a schedule's lock or close. device_id is the device, in the envelope; put_back_id is the same in each of one put-back's events.
| Type |
data |
put_back.armed |
{"put_back_id": 41, "key": "lock", "endpoint": 0, "value": true, "due_at": "2026-10-09T14:03:00Z", "cause": {"source": "remote", "actor": "cloud"}}: a put-back was written, before the command it answers went out. value is what it puts back, due_at when it falls due by the hub's clock, cause (Cause) its command's |
put_back.attempted |
{"put_back_id": 41, "key": "lock", "attempt": 1}: an attempt going out |
put_back.intervened |
{"put_back_id": 41, "key": "lock", "by": "person"}: a person changed the channel at the device, so the put-back won't run; it ends changed when it falls due |
put_back.clock_repaired |
{"put_back_id": 41, "key": "lock", "delta_ms": 3600000}: the hub's clock was corrected while the put-back waited, and its times, due_at among them, moved by delta_ms |
put_back.ended |
{"put_back_id": 41, "key": "lock", "attempts": 1, "reason": "confirmed"}: the put-back is over, after attempts attempts, for reason, below |
reason |
|
confirmed |
The device reported the value, after an attempt or, for a lock or garage door that was device.not_secured, later |
changed |
A person changed the channel at the device, or the device acknowledged another command to it, the same caller's included. A command refused or never delivered doesn't count |
cancelled |
The command it answers never went out |
forgotten |
The device was forgotten, or its channel was gone when the put-back fell due: removed, or the network reset. A lock or garage door's also has device.not_secured with reason forgotten |
not_confirmed |
Its attempt wasn't confirmed, on a channel other than a lock or garage door. A lock or garage door is device.not_secured instead, and its put-back stands until it ends confirmed or forgotten |
SmartStart
A code's id here is its setup code id without the sc_ prefix.
| Type |
data |
setup_code.added |
{"id": "3f2a9c0d1e4b5a67", "name": "Kitchen dimmer", "room": "Kitchen"}: a code went on the hub's list, or its name or room changed |
setup_code.removed |
{"id": "3f2a9c0d1e4b5a67"} |
setup_code.joined |
{"id": "3f2a9c0d1e4b5a67", "device_id": 21}: a device joined from the code |
setup_code.dropped |
{"ids": ["3f2a9c0d1e4b5a67"]}: the hub's network was reset, and its codes with it |
setup_code.unknown_request |
{"nwi_home_id": "EB49494C"}: a device asked to join and no code on the list admits it, at most once an hour per device. A join request carries only the device's NWI home ID: from its code's DSK, bytes 9 to 12 with the top two bits set and the lowest cleared, as 8 uppercase hex digits. Match it against your codes to tell which device asked; no match means a device whose code was never added |
Access
device_id is the lock, in the envelope.
| Type |
data |
user.created, user.updated |
{"user_id": 4, "label": "Unit 402 cleaner", "type": "general", "enabled": true, "schedule": {…}}: the user's fields; schedule null for always |
user.deleted |
{"user_id": 4, "label": "Unit 402 cleaner"} |
credential.created |
{"user_id": 4, "credential_id": 12, "slot": 3, "kind": "pin"} |
credential.applied |
{"credential_id": 12, "state": "active", "late_by_seconds": 40}: the lock confirmed the credential's state; late_by_seconds when it was written late |
credential.revoked |
{"credential_id": 12} |
credential.used |
{"user_id": 4, "credential_id": 12, "slot": 3, "method": "keypad"}: the lock opened with it. method is keypad, rfid or biometric; the ids are null for a slot no credential holds |
credential.rejected |
{"method": "keypad", "event": "…"}: the lock refused a credential. method is keypad, remote or unspecified |
credential.diverged |
{"credential_id": 12, "reported": "available"}: the lock reports its slot occupied or available, against what was confirmed |
credential.replaced |
{"credential_id": 12, "slot": 3}: a new credential took over the slot of this revoked or expired one, which the hub no longer keeps |
Automations
| Type |
data |
automation.created, automation.updated |
{"key": "lobby-door-left-open", "name": "Lobby door left open", "enabled": true, "revision": 4, "digest": "9f2c…"}: saved, switched on or off |
automation.deleted |
{"key": "lobby-door-left-open"} |
automation.suspended |
{"key", "reason": "loop", "chain": ["hall-on", "hall-off"]}: the hub switched it off, until it's enabled again. reason is loop: loop-blocked three times in ten minutes |
automation.loop_blocked |
{"key", "chain": [...], "reason": "depth"}: a run would have gone deeper than 8 (depth) or run an automation a third time in one chain (recurrence), so the hub dropped it |
automation.run_finished |
{"key", "run_id", "result", "failed": [step]}: result is completed, conditions_failed, stopped, timeout, crashed, disabled, missed or dropped_after_restart; failed lists the steps refused or failed |
automation.emitted |
{"name": "door_left_open", "severity": "warning", "data": {…}, "automation_key": "lobby-door-left-open", "run_id": "…", "trigger": {…}}: an emit step. Send your own notifications from it |
automation.unlocked |
{"key", "run_id", "channel": "lock", "trigger": {…}, "chain": [...]}: channel lock or barrier; an automation unlocked a lock or opened a garage door; device_id in the envelope |
schedule.updated |
{"key": "gym-door-hours", "name": "Gym door hours", "enabled": true} |
schedule.deleted |
{"key": "gym-door-hours"} |
schedule.applied |
{"key", "period", "values": {"lock": false}}: a period began and its values were sent. period names it: its index and the local date it began ("0:2026-10-12"), default:… out of every period, or untrusted on an untrusted clock |
calendar.updated |
{"key": "holidays", "dates": ["2026-12-25"]} |
calendar.deleted |
{"key": "holidays"} |
site.time_zone_set |
{"time_zone": "America/Toronto", "latitude": 43.65, "longitude": -79.38}: the hub took the site's time zone and location |
Intercoms
An intercom's events carry its ID as hub_id and no device_id. It also records the hub.* connection and alarm events above. One that couldn't reach the cloud sends its events when it reconnects, with the times they happened.
| Type |
data |
door.unlocked |
{"method": "code", "offline": false, "credential_id": 81, "call_id": null, "attempt_id": "ar_51c2"}: the door opened. method is code, qr, card, face, remote (POST /intercoms/{id}/door/unlock or an operator), call (the resident, during a call) or delivery. offline is true for an opening the intercom decided while the cloud was unreachable. credential_id, call_id and attempt_id are null when not known. A face's carries liveness: ir (the 1002L's IR check), rgb_only or none (a virtual intercom, with no IR camera); absent means ir |
door.state |
{"open": true}: the door sensor reports the door open or closed |
access.denied |
{"method": "code", "reason": "unknown", "credential_id": null}: a code, QR code, card, face or delivery was refused. reason is unknown, expired, not_yet_valid, not_allowed, no_match (face), not_live (face) or offline (the building couldn't be reached to check it). A face's carries liveness, as door.unlocked's |
call.started |
{"call_id": "c_8f2e41", "media": "video", "entry_id": 12, "unit": "402", "concierge": false}: a visitor called someone in the directory. media is video or voice; unit is absent for an entry without one |
call.answered |
{"call_id": "c_8f2e41"} |
call.ended |
{"call_id": "c_8f2e41", "outcome": "answered", "duration_s": 48}: outcome is answered, no_answer, fell_back (to a voice call, which starts its own call.started), cancelled or failed |
intercom.booted |
{"reason": "power_on"}: the intercom started. reason is power_on, reboot_requested, update, crash, watchdog or unknown |
intercom.power |
{"source": "poe"}: the supply the intercom runs on, recorded after each boot and on each change. source is dc (12 V DC), poe, both or unknown |
An intercom's alarms are hub.alarm_raised and hub.alarm_cleared, with alarm one of door_held, relay, reader, mcu, camera, ir_camera, audio, display or tamper.
Cause
cause is who or what changed a value or asked for a command. channel.observed and channel.recovered carry it, and so do device.not_secured and put_back.armed, with the cause of the put-back's command.
| Field |
|
source |
manual (at the device), keypad, rfid, biometric, button, auto (the device itself), remote, automation, schedule, hub (the hub's own work, such as a setup test), other_controller or unspecified |
slot, credential_id |
For keypad, rfid and biometric: the credential slot used, and the credential in it |
actor |
For remote: who asked; cloud for a command sent through this API |
automation, run_id, chain |
For automation: its key, the run, and the keys from the automation that started the chain to it |
schedule |
For schedule: its key |
The hub's own commands carry, by source:
source |
Fields |
Commands |
remote |
actor |
A client's or the cloud's command, its for put-back included |
automation |
automation, run_id, chain |
An automation's command, and its relock |
schedule |
schedule |
A schedule's command, its lock or close included |
A report that says nothing of its cause, of the value a command is waiting on, takes that command's cause; any other is unspecified.
Ignore event types you don't handle.