Skip to main content
WebSocket delivery provides real-time data streaming for live dashboards, monitoring applications, and event-driven architectures. With WebSocket delivery, your application connects to Kadoa’s WebSocket server to receive real-time notifications. Kadoa broadcasts events to your connected clients.

​
Prerequisites

We strongly recommend using our SDK for real-time updates. The SDK handles the connection, authentication, message acknowledgement, message replay and auto-reconnect.

​
How It Works

  1. You create a WebSocket channel in Kadoa (no URL needed - just enable WebSocket delivery)
  2. Your application connects to Kadoa’s WebSocket server via SDK with the API key
  3. Kadoa broadcasts events to your connected clients when events occur
Note: Only one WebSocket channel is allowed per workspace. All events are broadcast to the same channel based on your team ID.

​
Connection Details

  • WebSocket Server: Provided by Kadoa SDK
  • Authentication: Use your API key for authentication
If you need to implement a native WebSocket integration, please contact us for connection details and authentication requirements.

​
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": {}  // No configuration needed - leave empty
}
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 & Broadcasting

​
How Broadcasting Works

When you enable WebSocket delivery for a workflow:
  1. Kadoa monitors your workflow for changes
  2. When changes are detected, Kadoa broadcasts events to all connected clients

​
Message Structure

All messages are JSON objects with the following fields: Always present:
  • type: The type of the message (e.g., “workflow_data_change”, “heartbeat”)
  • timestamp: The timestamp when the message was sent (Unix timestamp in milliseconds)

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