Skip to content

WebSocket events

Subscribe to server notifications through the authenticated /events SockJS endpoint when you need live updates. Use the REST event API to read history.

Connect and authenticate

The server exposes a STOMP broker through SockJS at https://{server}:8443/events. A client that opens a WebSocket directly can use wss://{server}:8443/events/websocket. Replace the host, port, and scheme for your deployment. Authenticate the HTTP handshake with a valid Bearer JWT that has VIEW_RESOURCES; send Authorization: Bearer {ACCESS_TOKEN} on the WebSocket upgrade request. A STOMP CONNECT header alone cannot authenticate the HTTP handshake. The server applies its browser origin rules before accepting a cross-origin connection.

Subscriptions use /topic destinations. Clients may subscribe and receive messages, but cannot publish STOMP messages to the server. Unknown topic subscriptions are ignored. The server checks current permissions during the connection, including before delivering messages. Reconnect with a current access token when the token expires; refreshing a REST token does not renew an existing WebSocket connection.

Subscribe to topics

The message body is JSON. The topic determines its shape:

Topic JSON body Required authority
/topic/agent, /topic/agent/heartbeat Agent GUID string VIEW_RESOURCES
/topic/agent/active Object with agentGuid and active VIEW_RESOURCES
/topic/agent/metadata Agent metadata response VIEW_RESOURCES
/topic/command/sent, /topic/command/result Command response VIEW_RESOURCES
/topic/command-templates/new, /topic/command-templates/removed Command template response VIEW_RESOURCES
/topic/command-alias/new, /topic/command-alias/removed Command alias response VIEW_RESOURCES
/topic/listener/new, /topic/listener/removed, /topic/listener/modified Listener response VIEW_RESOURCES
/topic/payload/new, /topic/payload/archived Payload response VIEW_RESOURCES
/topic/users/new, /topic/users/modified User response MANAGE_USERS
/topic/events/by-type/{REFERENCE_TYPE} Event response with actor, time, and references VIEW_RESOURCES, except USER requires MANAGE_USERS

For event topics, replace {REFERENCE_TYPE} with an uppercase reference type: AGENT, COMMAND, COMMAND_ALIAS, NOTE, DISCOVERED_HOST, DISCOVERED_SERVICE, DISCOVERED_CREDENTIAL, JOB, LISTENER, FILE, PAYLOAD, SETTING, or USER. A user-topic subscription also needs VIEW_RESOURCES to establish the connection. Event responses use the same event fields as the REST event API; setting events omit referenced setting data so subscribers do not receive settings they cannot view.

For example, a STOMP subscription to command result notifications uses:

1
2
3
4
5
SUBSCRIBE
id:command-results
destination:/topic/command/result

\0

Command result notifications limit each text or binary entry to 50KB by default. If an entry has type: "omitted", fetch the complete result through GET /api/v1/commands/{COMMAND_ID}. For missed notifications or earlier activity, search GET /api/v2/events.