WebSockets

Broadcast decoded events to a live topic and subscribe from your own client.

A WebSocket trigger broadcasts a payload to a named topic instead of pushing it to a URL. It is the right choice when the consumer is a browser, a dashboard, or any long-lived client that wants events as they happen and does not want to expose an endpoint of its own.

Configuring one#

Drag a WebSocket node onto the canvas, name it, add broadcast inputs, wire values into them, and write a buildPayload function returning a JSON string — exactly as for a webhook.

Save the canvas. The platform then issues two read-only values on the node:

Issued on first save
Field	Type	Description
Topic	read-only	The channel name subscribers connect to. Globally unique, and derived from the trigger rather than from a database row id.
Connection key	read-only secret	Required to subscribe. Validated before the socket is upgraded — an invalid key closes the connection.

Subscribing#

Open a WebSocket to the platform's /ws endpoint with the topic and key as query parameters. Each message is the JSON string your payload builder returned.

subscribe.ts

TypeScript

const socket = new WebSocket(
  `wss://<your-syncro-host>/ws?topic=${TOPIC}&key=${CONNECTION_KEY}`,
);

socket.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  render(payload);
};

socket.onclose = (event) => {
  // An invalid key closes the socket immediately — do not hammer the
  // server in that case. Back off, and re-check the key.
  console.warn("closed", event.code, event.reason);
};

Topic names#

Topics follow the shape idx_<reference>_<trigger-name>, where the trigger name is slugified. They are unique across the whole platform, so a topic name never collides with another tenant's.

Delivery semantics#

A WebSocket topic is a live broadcast, not a queue. This is the most important difference from webhooks:

No buffering. Events published while nobody is connected are not stored and cannot be replayed. A client that reconnects after a gap has missed what happened during it.
No retries. There is no acknowledgement, so there is nothing to retry.
Fan-out. Every connected subscriber to a topic receives every message on it.

If missing an event is unacceptable, the durable path is your database — the same event that was broadcast has also been written to your tables. Use the socket for immediacy and the table as the record.

Reconnecting#

Clients drop for ordinary reasons — laptops sleep, networks change. Reconnect with exponential backoff and a cap. Distinguish a transient close from a rejected key: if the key is wrong, reconnecting will never succeed, and a tight retry loop just wastes both ends.