WebSocket Trigger

Run a workflow from messages sent over a WebSocket connection, and relay messages between connected peers.

Overview

A WebSocket trigger gives the workflow a realtime endpoint. Browsers connect to it with ?room=ID, and every message is relayed to the other peers in that room. Relaying happens in the runtime and consumes no workflow runs. Turn on Run the flow on every message when the workflow should also process each message, for example to save chat messages or answer with an AI model through a Realtime Send node.

Endpoint

Field	Description	Default
`Path`	The endpoint path, for example `realtime/chat`	-

Authentication

Field	Description	Default
`Require Authentication`	Validate a JWT during the connection handshake	On
`Token Source`	`Subprotocol`, `Query param` or `First message`. Subprotocol sends `['ubex.jwt', '<token>']` as the WebSocket protocols and is recommended, because query strings end up in access logs	Subprotocol
`JWT Secret`	A secret from the Vault	-
`Algorithm`	`HS256`, `HS384` or `HS512`	HS256

Rooms and broadcast

Field	Description	Default
`Broadcast Mode`	`All peers (including sender)`, `Other peers (exclude sender)` or `Targeted (flow decides)`	Other peers
`Who can join a room`	`Any room`, or `Match pattern` to restrict rooms. With Any room, any authenticated connection can join any room, including one that belongs to someone else	Any room
`Max Peers Per Room`	Connections per room	50
`Max Concurrent Rooms`	Rooms open at the same time	100

Presence

Field	Description	Default
`Emit Presence Events`	Tell the room when a peer joins or leaves	On
`Identity Claim`	JWT claim used as `sender_id`	`email`

Flow invocation

Field	Description	Default
`Run the flow on every message`	Leave off to only relay messages in the runtime, without consuming workflow runs	Off

Advanced

Field	Description	Default
`Sender Identity`	`Server (from the token)` or `Client (trust the payload)`. Server identity overwrites any sender field in the payload, so a peer cannot claim to be someone else	Server
`Max Payload Size`	Bytes per message	65536
`Rate Limit`	Messages per second, per connection	30
`Ping Interval`	Seconds	30
`Pong Timeout`	Seconds before the peer is considered gone	10
`Idle Timeout`	Seconds. Ping and pong count as activity	86400
`CORS Origins`	Optional list of allowed origins	-

Best Practices

Keep Require Authentication on, and use Match pattern so users can only join their own rooms.
Leave Run the flow on every message off for plain chat relays; turn it on only when each message needs processing.