Skip to main content
Configure notifications to integrate Kadoa events into your applications and automation workflows.

​
SDK Methods

​
Setup Workflow Notifications

// Email notifications
await client.notification.setupForWorkflow({
  workflowId: 'your-workflow-id',
  events: ['workflow_finished', 'workflow_failed'],
  channels: { EMAIL: true }
});

// Custom email recipients
await client.notification.setupForWorkflow({
  workflowId: 'your-workflow-id',
  events: ['workflow_finished'],
  channels: {
    EMAIL: {
      name: 'team-notifications',
      recipients: ['team@example.com']
    }
  }
});

// Slack notifications
await client.notification.setupForWorkflow({
  workflowId: 'your-workflow-id',
  events: ['workflow_failed'],
  channels: {
    SLACK: {
      name: 'alerts',
      webhookUrl: 'https://hooks.slack.com/services/YOUR/WEBHOOK'
    }
  }
});

// Webhook notifications
await client.notification.setupForWorkflow({
  workflowId: 'your-workflow-id',
  events: ['workflow_finished'],
  channels: {
    WEBHOOK: {
      name: 'api-integration',
      url: 'https://api.example.com/webhooks/kadoa',
      httpMethod: 'POST'
    }
  }
});

​
Real-time WebSocket Updates

const client = new KadoaClient({
  apiKey: 'your-api-key',
  enableRealtime: true
});

client.realtime?.onEvent((event) => {
  console.log('Event received:', event.type, event.data);
});

​
Channel Management

// List channels
const channels = await client.notification.channels.listChannels({});

// Delete a channel
await client.notification.channels.deleteChannel('channel-id');

​
Overview

Notifications can be configured at two levels:
  • Workspace-Level Settings: Apply to all workflows unless a specific workflow has its own notification settings
  • Workflow-Level Settings: Apply only to a single workflow
When both levels exist, workflow-level settings override workspace-level ones.
You can have only one setting per event type at each level (workflow or workspace). To add more channels to an existing setting, send a PUT request to update it.

​
Configure Notifications via API

​
Step 1: Create Notification Channels

First, create the channels you want to use for notifications. See Webhooks and WebSockets for channel creation examples.

​
Step 2: Subscribe to Events

Subscribe to events by sending a POST request to /v5/notifications/settings.

​
Workspace-Level Subscription

Apply notifications to all workflows: 
// POST /v5/notifications/settings
{
  "eventType": "workflow_finished",
  "eventConfiguration": {},
  "enabled": true,
  "channelIds": ["<channel-id>"]
}

​
Workflow-Level Subscription

Apply notifications to a specific workflow: 
// POST /v5/notifications/settings
{
  "workflowId": "<your-workflow-id>",
  "eventType": "workflow_data_change",
  "eventConfiguration": {},
  "enabled": true,
  "channelIds": ["<channel-id>"]
}

​
Step 3: Update Existing Settings

To add more channels to existing settings, use a PUT request: 
// PUT /v5/notifications/settings/<settings-id>
{
  "channelIds": ["existing-channel-id", "new-channel-id"]
}

​
Event Types

​
workflow_data_change

Triggered when data changes are detected in monitored workflows. See the Retrieve Historical Changes section for how to fetch change data. Configuration: 
{
  "workflowId": "<workflow-id>",
  "eventType": "workflow_data_change",
  "eventConfiguration": {},
  "enabled": true,
  "channelIds": ["webhook-channel-id", "websocket-channel-id"]
}
Use cases: Price monitoring, inventory tracking, content change detection

​
workflow_finished

Triggered when a workflow completes successfully. Configuration: 
{
  "eventType": "workflow_finished",
  "eventConfiguration": {},
  "enabled": true,
  "channelIds": ["slack-channel-id", "email-channel-id"]
}
Use cases: Scheduled job completion, batch processing notifications

​
workflow_failed

Triggered when a workflow fails during execution. Configuration: 
{
  "eventType": "workflow_failed",
  "eventConfiguration": {},
  "enabled": true,
  "channelIds": ["pagerduty-channel-id", "email-channel-id"]
}
Event Payload: 
{
  "eventType": "workflow_failed",
  "workflowId": "wf_123",
  "runId": "run_456",
  "errors": [{
    "errorCode": "ANTIBOT_DETECTION",
    "severity": "CRITICAL",
    "message": "Access blocked by bot protection",
    "timestamp": "2025-01-15T10:30:00Z",
    "context": {
      "url": "https://example.com/page",
      "httpStatus": 403
    }
  }]
}
Use cases: Error monitoring, production alerts

​
workflow_data_quality_issue

Triggered when data validation issues are detected. Configuration: 
{
  "workflowId": "<workflow-id>",
  "eventType": "workflow_data_quality_issue",
  "eventConfiguration": {},
  "enabled": true,
  "channelIds": ["webhook-channel-id"]
}
Use cases: Data quality monitoring, validation alerts

​
Testing Notifications

After configuring notifications, test your settings using the test endpoint: 
// POST /v5/notifications/test
{
  "eventType": "workflow_finished",
  "workflowId": "optional-workflow-id"
}
This sends a mock notification event to verify your configuration.

​
Retrieve Historical Changes

The /changes endpoint returns all historical data changes detected by your monitoring workflows. By default, it returns changes from all your active workflows. View full API reference → 
GET https://api.kadoa.com/v4/changes
You can filter changes by workflow and date range using query parameters: 
GET https://api.kadoa.com/v4/changes?startDate=2024-11-01T00:00:00Z&endDate=2024-11-30T23:59:59Z

​
Response Format

Each change includes a differences array showing structured representations of what changed: 
{
  "differences": [
    {
      "type": "changed",
      "fields": [
        {
          "key": "title",
          "previousValue": "Old Title",
          "value": "New Title"
        }
      ]
    }
  ]
}
The differences field structure:
  • type: The type of change - added, removed, or changed
  • fields: All fields of the object (even if unchanged)
Each field change includes:
  • key: Field name that was changed
  • value: Current field value
  • previousValue: Previous field value (only for changed type)
Learn more about change detection →

​
Complete Setup Example

Here’s a complete example of configuring notifications for different use cases:

​
Step 1: Create Channels

// POST /v5/notifications/channels
{
  "channelType": "WEBHOOK",
  "name": "Data Changes Webhook",
  "config": {
    "webhookUrl": "https://your-endpoint.com/webhook",
    "httpMethod": "POST"
  }
}

​
Step 2: Subscribe to Events

// POST /v5/notifications/settings
// Workspace-level: Notify on all workflow completions
{
  "eventType": "workflow_finished",
  "eventConfiguration": {},
  "enabled": true,
  "channelIds": ["email-channel-456"]
}
⌘I