> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.rhombus.community/llms.txt
> Use this file to discover all available pages before exploring further.

# WebSocket Overview

> Stream real-time security events from Rhombus over WebSocket and STOMP — receive policy alerts, device updates, and activity instantly without polling the API.

The Rhombus platform exposes a WebSocket endpoint for real-time, bidirectional communication between your application and the Rhombus console. This allows you to receive instant notifications about security events, policy alerts, device changes, and other organizational activity without polling the REST API.

## 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.

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

## Connection Endpoint

| Environment | Endpoint                                     |
| ----------- | -------------------------------------------- |
| Production  | `wss://ws.rhombussystems.com:8443/websocket` |

## Key Concepts

### Topics

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

```text theme={null}
/topic/change/{orgUuid}
```

This topic emits events for all changes within your organization, including policy alerts, device updates, and configuration changes.

### Event Types

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

| Field        | Description                                                            |
| ------------ | ---------------------------------------------------------------------- |
| `entity`     | The type of entity that changed (e.g., `POLICY_ALERT`, `CAMERA_STATE`) |
| `entityUuid` | Unique identifier for the entity                                       |
| `type`       | The change type: `REFRESH` (default), `CREATE`, `UPDATE`, or `DELETE`  |
| `update`     | The changed entity data (present on some events)                       |
| `deviceUuid` | Associated device UUID (when applicable)                               |

### Authentication

WebSocket connections authenticate using **API tokens only**. Certificate-based (mTLS) authentication is not supported for WebSocket. The token is passed as an HTTP header during the WebSocket handshake.

<Note>
  If you currently authenticate to the Rhombus REST API using certificates, you will need a separate API token for WebSocket connections.
</Note>

## When to Use WebSocket vs. REST API

| Use Case                      | Recommended Approach      |
| ----------------------------- | ------------------------- |
| React to alerts in real time  | WebSocket                 |
| Build a live dashboard        | WebSocket                 |
| Trigger automations on events | WebSocket                 |
| Query historical data         | REST API                  |
| Manage devices or users       | REST API                  |
| Retrieve video clips          | REST API (DASH streaming) |

## What's Next

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/websocket/authentication">
    Configure API token authentication for WebSocket connections.
  </Card>

  <Card title="Connection Lifecycle" icon="arrows-rotate" href="/websocket/connection-lifecycle">
    Establish, maintain, and gracefully close connections.
  </Card>

  <Card title="Event Monitoring" icon="bell" href="/websocket/event-monitoring">
    Subscribe to topics and process real-time events.
  </Card>

  <Card title="Code Examples" icon="code" href="/websocket/code-examples">
    Full working examples in Python, JavaScript, and Go.
  </Card>
</CardGroup>