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

​
Prerequisites

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 → 
// 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. Screenshot of WebSocket channel creation in workspace UI

​
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 → 
// 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
Screenshot of WebSocket channel selection in workspace UI Screenshot of WebSocket channel selection in workflow UI
  1. Subscribe to events by selecting the WebSocket channel in workspace settings or workflow-specific settings
Screenshot of WebSocket channel selection in workspace UI Screenshot of WebSocket channel selection in workflow UI

​
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
}