WebSocket Overview

The Rhombus platform exposes a WebSocket endpoint that streams real-time events to your application. This allows you to receive instant notifications about security events, policy alerts, device changes, and other organizational activity without polling the REST API. For integrations the connection is receive-only: you subscribe to topics, and use the REST API to act.

How it works

Rhombus WebSocket connections use the STOMP 1.2 (Streaming Text Oriented Messaging Protocol) messaging protocol layered on top of a standard WebSocket connection. STOMP provides a simple, frame-based protocol for subscribing to topics and receiving structured messages.

Your Application
      │
      ▼
  WebSocket (WSS)
      │
      ▼
  STOMP 1.2 Protocol
      │
      ▼
  Rhombus Event Bus ──► /topic/change/{orgUuid}

Connection endpoint

Connect to the endpoint matching your organization's region:

Key concepts

Topics

Once connected, you subscribe to a topic to receive messages. The primary topic for organizational events is:

/topic/change/{orgUuid}

This topic emits change events for your organization, including policy alerts, device updates, and configuration changes. A connection receives only the events its credential's role can see, policy alerts included: a full-access role receives everything, and events for devices or locations outside the role are dropped without an error. See What a connection receives.

Event types

Each message on the change topic contains a JSON payload with:

Authentication

The WebSocket handshake carries the credential. The event WebSocket accepts an API key (standard or partner) or an OAuth access token with the read scope, sent as headers from a server, or a federated token, which can also go in the URL so a browser can connect directly. Partner credentials must also send the client organization in the x-auth-org header. Deleting or revoking a credential closes its open connections within 60 seconds.

When to use WebSocket vs. REST API

What's Next