WebSocket
WebSocket Event Reference
Every message on the Rhombus event WebSocket's change destination: the envelope, policy alert changes, other entity changes, STOMP headers, change types and delivery guarantees, generated from the AsyncAPI specification.
On this page
This page lists the messages a subscriber to /topic/change/{orgUuid} receives. It is generated from the event WebSocket's AsyncAPI specification; the policy alert fields and their enums come from the same schemas as the API Reference. To connect and subscribe, see the WebSocket overview and WebSocket authentication.
Delivery
- At most once. Messages aren't acknowledged, stored or replayed. Anything published while you are disconnected is lost, and a message the service can't process within 30 seconds of publication is dropped. After a reconnect, read what you missed from the REST API; Build an event pipeline shows how.
- Filtered by role. A connection receives only what its credential's role can see. A policy alert is delivered when the role can access the alert's device or location; an alert with neither goes only to full-access roles. A role limited to some locations or devices receives only the entity types the server can check against them. See What a connection receives.
- No ordering guarantee. Order events by their timestamps, not by arrival.
- Frames. The body is JSON, although the frame's
content-typeheader saystext/plain;charset=UTF-8. Key order varies, and null fields are left out. UUIDs are strings, including those in thetargetUsersandtargetRolesarrays that some messages carry. - Not every change is sent. Many entity types send a short
REFRESHwith noupdate; read the entity from the REST API when you need its state. Seek points and bounding boxes for live video aren't sent on this destination. - New values appear without notice: new entity types, change types, fields and enum values. Ignore what you don't recognize.
Change types
type | Meaning | update |
|---|---|---|
CREATE | Something new, such as a policy alert | Usually the whole object |
UPDATE | An existing object changed | The new state, the changed fields, or nothing |
REFRESH | The object changed; read it again if you need its state | Usually none |
DELETE | The object was removed | None |
Messages you receive
| Message | Summary |
|---|---|
PolicyAlertChangeEvent | A new policy alert, or a change to one. |
ChangeEvent | Any other change: device state, sensors, access control, policies, clips and more. |
PolicyAlertChangeEvent
A new policy alert, or a change to one.
A CREATE carries the whole alert in update; it is sent once, when the alert is first stored, so fields that Rhombus fills in later (such as finalized and clip locations) can still be at their initial values. Read the alert from the REST API when you need its final state. UPDATE and DELETE carry only entityUuid. DELETE messages are limited to one per organization every 10 minutes, so don't rely on them to track every removed alert. A policy alert is delivered only to a role that can access the alert's device or location; an alert with neither goes only to full-access roles.
Headers
The organization.
Same as the body's entity.
Same as the body's entityUuid, when set.
Same as the body's deviceUuid, when set.
Body
Available options: POLICY_ALERT
CREATE: a new alert, with the whole alert in update. UPDATE: the alert was linked to an alarm-monitoring threat case (no update). DELETE: the alert was removed or archived (no update).
Available options: CREATE, UPDATE, DELETE
The alert's UUID on UPDATE and DELETE. Absent on CREATE: use update.uuid.
The requested policy alert
The users the message is addressed to, as UUID strings. Set only on some messages.
The roles the message is addressed to, as UUID strings. Set only on some messages.
{
"entity": "POLICY_ALERT",
"type": "CREATE",
"update": {
"alertMonitoringVerified": false,
"clipLocationMap": {},
"clipLocationMapV2": {},
"deviceType": "CAMERA",
"deviceUuid": "ItkwWv1qT7Wy8-pY8KDesw",
"durationSec": 12,
"egressBoundaryDevices": [],
"finalized": false,
"ingressBoundaryDevices": [],
"locationUuid": "Rk2pQ7yLT0qX4b1nVt8sJw",
"notificationSent": false,
"numHumans": 1,
"orgUuid": "wEeifGSySTiD228kK7M-Xg",
"policyAlertTriggers": [
"MOTION_HUMAN"
],
"policyUuid": "pL0c7YvHQkWm3rN2aB9xCg",
"ruleUuid": "rU1e9KdLR3uJ5sP0qW2tYg",
"saved": false,
"serverReceivedAtMs": 1791367200850,
"shared": false,
"textDescription": "Human detected at Front Lobby",
"timestampMs": 1791367200000,
"type": "POLICY_ALERT_V2",
"uuid": "Xq3vT1bKQ2m8c9Zr0aLwYg"
}
}ChangeEvent
Any other change: device state, sensors, access control, policies, clips and more.
The generic envelope for every entity except POLICY_ALERT. The shape of update depends on entity; many messages carry none, so treat them as a signal to read the entity from the REST API.
Headers
The organization.
Same as the body's entity.
Same as the body's entityUuid, when set.
Same as the body's deviceUuid, when set.
Body
The kind of entity that changed. Filter on it client-side.
Available options: ALARM_MONITORING_LOCATION_SETTINGS, ALARM_MONITORING_LICENSE, DEVICE, LOCATION, POLICY, POLICY_ALERT, POLICY_ADDENDUM, POLICY_PAUSE, USER, CAMERA_USER_CONFIG, ORG, USER_PERMISSION_GROUP, PARTNER_PERMISSION_GROUP, VIDEO_WALL, SHARED_CLIPS, SAVED_CLIPS, SHARED_STREAMS, SPLICED_CLIPS, TIMELAPSE, AUDIT_EVENTS, DIAGNOSTIC_EVENTS, CAMERA_STATE, CLIMATE_STATE, DOOR_STATE, NVR_STATE, OCCUPANCY_STATE, PROXIMITY_STATE, AUDIO_STATE, CAMERA, NVR, DOOR_SENSOR, CLIMATE_SENSOR, PROXIMITY_SENSOR, BOUNDING_BOX, SEEK_POINT, SENSOR_SEEK_POINT, SCHEDULE, FACE_EVENT, DEVICE_SHADOW, THREAT_CASE, THREAT_CASE_REVIEWER, KEYPAD, COMPONENT_DOOR_READER_SHADOW, COMPONENT_DOOR_RELAY_SHADOW, COMPONENT_DOOR_POSITION_INDICATOR_SHADOW, COMPONENT_APERIO_GATEWAY_SHADOW, COMPONENT_APERIO_DOOR_EXT_SHADOW, COMPONENT_SCHLAGE_GATEWAY_SHADOW, COMPONENT_SCHLAGE_DOOR_EXT_SHADOW, COMPONENT_REQUEST_TO_EXIT_SHADOW, COMPONENT_GENERIC_RELAY_SHADOW, COMPONENT_GENERIC_INPUT_SHADOW, COMPONENT_GENERIC_BUTTON_SHADOW, ACCESS_CONTROLLED_DOOR_SHADOW, ACCESS_CONTROLLED_DOOR, ACCESS_CONTROLLED_ELEVATOR_SHADOW, ACCESS_CONTROLLED_ELEVATOR, ACCESS_CONTROLLED_ELEVATOR_LANDING_SHADOW, ACCESS_CONTROLLED_ELEVATOR_LANDING, COMPONENT_SEEKPOINT, ROBOT_SEEKPOINT, VEHICLE_EVENT, DEVICE_INTEGRATION, SHELLY_INTEGRATION, THIRD_PARTY_CAMERA_DISCOVERY, THIRD_PARTY_CAMERA_ASSIGNMENT, THIRD_PARTY_CAMERA_CREDENTIAL, CHATBOT_QUERY, KEYPAD_COMMAND, PRIORITY_DETECTION, LIVE_DETECTION, LIVE_OCCUPANCY, UNKNOWN
The entity that changed, as a 22-character base64url UUID. Absent on policy alert CREATE messages.
The kind of change. REFRESH (the default) means the entity changed and carries little or no detail: read it again from the REST API if you need its current state. CREATE and UPDATE usually carry the entity in update; DELETE never does.
Available options: REFRESH, DELETE, CREATE, UPDATE
The device involved, with an optional facet suffix (.v0). Set only on some messages, such as FACE_EVENT.
The sub-location path, as dot-separated location UUIDs. Set only on some alarm-monitoring messages.
The users the message is addressed to, as UUID strings. Set only on some messages.
The roles the message is addressed to, as UUID strings. Set only on some messages.
The entity's new state or the changed fields. Its shape depends on entity, and it is absent on DELETE, on most REFRESH messages and on some UPDATE messages.
{
"entity": "CAMERA_STATE",
"entityUuid": "ItkwWv1qT7Wy8-pY8KDesw",
"type": "UPDATE",
"update": {
"connectionStatus": "GREEN",
"firmwareVersion": "v1.0.1234",
"healthStatus": "GREEN",
"locationUuid": "Rk2pQ7yLT0qX4b1nVt8sJw",
"mediaRegion": "us-west-2",
"name": "Front Lobby",
"stateUpdatedTimestampMs": 1791367200000,
"uuid": "ItkwWv1qT7Wy8-pY8KDesw"
}
}