1KEY Developers
Reference

Event reference

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.