Skip to main content
WebSocket is the step type for collecting live, in-play data over a long-running WebSocket connection. You add a WebSocket step to a project when you need to keep a socket open and publish data continuously as messages arrive, instead of polling an endpoint on an interval.

​
When to Use WebSocket

Use a WebSocket step when:
  • The source streams live, in-play updates over a WebSocket connection.
  • You need a persistent connection that publishes on every update (and on a heartbeat), rather than one result per scheduled run.
  • You want event-driven hooks (on connect, on message, on interval, on close) to subscribe, transform, and publish streaming data.
For request/response polling, use HTTP Commands.

​
Adding a WebSocket Step

1

Add a step and set the technology

In your project’s Scraping flow, add a step and set Technology Used to WebSocket (step type WEBSOCKET).
2

Add the WebSocket command

Add the WebSocket command as the first command in the step and set the connection url.
3

Configure the event hooks

Use onConnect to send subscription messages, onMessage to parse and publish each incoming message, and onInterval / heartbeatIntervalMs to keep the connection alive and re-publish on a cadence.
4

Publish results

Add Parse and Sink commands inside the hooks to transform and deliver the streamed data.

​
Supported Protocols

WebSocket supports three protocol variants. Set the protocol parameter on the WebSocket command to select one (defaults to native).

​
Limits and Behaviors

​
Mid-flow vs. streaming steps

  • A WebSocket step that is not the last step in the flow opens the connection, captures an initial dump, then closes the connection. It publishes its captured result once.
  • The last step in the flow keeps the socket open and publishes results on each heartbeat, continuously streaming live updates downstream.
See Worked Example: Sports, Events, Event Data for a full sports -> events -> event-data flow.

​
Hooks

A WebSocket step is driven by event hooks — onConnect, onMessage, onInterval, onClose, and onError. For exactly when each hook fires (including the connect-then-buffer-then-process ordering) and how heartbeatIntervalMs re-publishes the current result, see Hook Firing Semantics in the WebSocket command reference — the canonical source.

​
Snapshots and Deltas

Live feeds usually send an initial snapshot of the full state followed by incremental deltas carrying only what changed. A WebSocket step accumulates state across frames: your onMessage commands read and update values held in state, merging the snapshot and later deltas into one complete event before publishing. Because state persists for the life of the connection, the streaming step can always publish the current, fully merged event, including on a heartbeat tick when no new delta has arrived.

​
Available Commands

WebSocket

Long-running WebSocket with full event-hook support

WebSocket Send

Send a message over the active WS connection

WebSocket Close

Cleanly close the active WS connection

​
Common Use Cases

  • Live Odds Feeds: Subscribe to in-play sports feeds and publish updates as they stream in.
  • Long-Running Connections: Maintain connections that receive many messages over time.
  • Heartbeat Patterns: Use onInterval and heartbeatIntervalMs to keep the connection alive and re-publish the current result.