WebSocket

Real-time data streaming with WebSockets

WebSocket delivery provides real-time data streaming for live dashboards, monitoring applications, and event-driven architectures.

Prerequisites

• A Kadoa account
• Access to an existing team (Team features)
• Get an API key
• SDKs

We strongly recommend using our SDK for real-time updates. The SDK handles the connection, authentication, message acknowledgement, message replay and auto-reconnect. If you need to implement a native WebSocket integration, please contact us.

API Configuration

Step 1: Create a WebSocket Channel

First, create a WebSocket channel by making a POST request to /v5/notifications/channels:

View full API reference →

Request

// POST /v5/notifications/channels
{
  "channelType": "WEBSOCKET",
  "name": "Real-time Data Changes",
  "config": {}
}

The response will include an id in the channel object that you’ll need for the next step.

Step 2: Subscribe to Data Changes

Once you have the channel ID, subscribe to data changes events by making a POST request to /v5/notifications/settings:

View full API reference →

Request

// POST /v5/notifications/settings
{
  "workflowId": "<your-workflow-id>",
  "eventType": "workflow_data_change",
  "eventConfiguration": {},
  "enabled": true,
  "channelIds": ["<channel-id-from-step-1>"]
}

UI Configuration

You can also configure WebSocket channels through the UI:

1. Add a WebSocket channel via the notifications tab in the left sidebar or notifications tab in a workflow

2. Subscribe to events by selecting the WebSocket channel in workspace settings or workflow-specific settings

Message Format

All messages are JSON objects with the following fields:

Always present:

• type: The type of the message.
• timestamp: The timestamp of the message.

Optional depending on the type:

• data: The data of the message.
• id: The ID of the message used for acknowledgement.

Message Types

workflow_data_change

This message is sent when a workflow data changes.

Fields:

id · string

The change ID of the workflow. You can also retrieve the change with screenshot over the /changes endpoint or view the change in the Kadoa dashboard like: https://www.kadoa.com/data-diff/ID

workflowId · string

The ID of the workflow. Accessible over the /workflows endpoint or the Kadoa dashboard like: https://www.kadoa.com/workflow/WORKFLOW_ID

data · object

The data of the workflow. Full snapshot of the data at the time of the change.

differences · array

Structured representation of changes with object-based diffing. For an explanation of the differences format, please refer to the monitoring API documentation.

url · string

The URL of the page the workflow is monitoring.

createdAt · string

The timestamp in ISO format when the change was detected.

Example:

{
  "type": "workflow_data_change",
  "timestamp": 1736367604663,
  "id": "2df91fbd-74c1-4d11-91aa-50030393574b",
  "data": {
    "id": "66d0c9e65baad1694a2132d0",
    "workflowId": "677fc12545e790b20a4eec34",
    "data": [{ "title": "Test News" }, { "title": "New News" }],
    "differences": [
      {
        "type": "added",
        "fields": [
          {
            "key": "title",
            "value": "New News"
          }
        ]
      }
    ],
    "url": "https://thisismymonitoredpage.com",
    "createdAt": "2025-01-09T10:00:00Z"
  }
}

---

heartbeat

Reconnection logic is handled by the SDK. If you implement a native WebSocket integration, you might need to handle reconnections yourself.

This message is sent every 15 seconds. It’s used to keep the connection alive. If you don’t receive a heartbeat after 30 seconds, the connection is considered lost, reconnection is needed.

Example:

{
  "type": "heartbeat",
  "timestamp": 1736367604663
}