Skip to main content
Notifications alert you when workflows complete, fail, or detect data changes. You can receive them via email, webhooks, or WebSockets. The SDK handles channel management automatically.
For event types and channel details, see Notifications.

​
Prerequisites

  • Kadoa account with API key
  • SDK installed: npm install @kadoa/node-sdk or uv add kadoa-sdk

​
Quick Start

import { KadoaClient } from "@kadoa/node-sdk";

const client = new KadoaClient({ apiKey: "YOUR_API_KEY" });

await client.notification.setupForWorkflow({
  workflowId: "YOUR_WORKFLOW_ID",
  events: ["workflow_data_change"],
  channels: {
    WEBHOOK: {
      name: "my-webhook",
      webhookUrl: "https://your-server.com/webhook",
      httpMethod: "POST",
    },
  },
});

from kadoa_sdk import KadoaClient, KadoaClientConfig
from kadoa_sdk.notifications import SetupWorkflowNotificationSettingsRequest

client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))

client.notification.setup_for_workflow(
    SetupWorkflowNotificationSettingsRequest(
        workflow_id="YOUR_WORKFLOW_ID",
        events=["workflow_data_change"],
        channels={
            "WEBHOOK": {
                "name": "my-webhook",
                "webhookUrl": "https://your-server.com/webhook",
                "httpMethod": "POST",
            }
        },
    )
)

> "Set up a webhook notification on my 'Product Monitor' workflow that triggers on data changes, sending to https://your-server.com/webhook"
The SDK reuses existing channels with the same name. Running setup multiple times won’t create duplicates.

​
Channel Types

​
Email

// Use account email
await client.notification.setupForWorkflow({
  workflowId: workflowId,
  events: ["workflow_finished", "workflow_failed"],
  channels: { EMAIL: true },
});

// Or specify recipients
await client.notification.setupForWorkflow({
  workflowId: workflowId,
  events: ["workflow_finished"],
  channels: {
    EMAIL: {
      name: "team-notifications",
      recipients: ["team@example.com"],
    },
  },
});

# Use account email
client.notification.setup_for_workflow(
    SetupWorkflowNotificationSettingsRequest(
        workflow_id=workflow_id,
        events=["workflow_finished", "workflow_failed"],
        channels={"EMAIL": True},
    )
)

# Or specify recipients
client.notification.setup_for_workflow(
    SetupWorkflowNotificationSettingsRequest(
        workflow_id=workflow_id,
        events=["workflow_finished"],
        channels={
            "EMAIL": {
                "name": "team-notifications",
                "recipients": ["team@example.com"],
            }
        },
    )
)

​
Slack

await client.notification.setupForWorkflow({
  workflowId: workflowId,
  events: ["workflow_failed"],
  channels: {
    SLACK: {
      name: "team-notifications",
      slackChannelId: "C1234567890",
      slackChannelName: "alerts",
      webhookUrl: "https://hooks.slack.com/services/YOUR/WEBHOOK",
    },
  },
});

client.notification.setup_for_workflow(
    SetupWorkflowNotificationSettingsRequest(
        workflow_id=workflow_id,
        events=["workflow_failed"],
        channels={
            "SLACK": {
                "name": "team-notifications",
                "slackChannelId": "C1234567890",
                "slackChannelName": "alerts",
                "webhookUrl": "https://hooks.slack.com/services/YOUR/WEBHOOK",
            }
        },
    )
)

​
Webhook

await client.notification.setupForWorkflow({
  workflowId: workflowId,
  events: ["workflow_data_change", "workflow_finished"],
  channels: {
    WEBHOOK: {
      name: "api-integration",
      webhookUrl: "https://api.example.com/webhooks/kadoa",
      httpMethod: "POST",
    },
  },
});

client.notification.setup_for_workflow(
    SetupWorkflowNotificationSettingsRequest(
        workflow_id=workflow_id,
        events=["workflow_finished"],
        channels={
            "WEBHOOK": {
                "name": "api-integration",
                "webhookUrl": "https://api.example.com/webhooks/kadoa",
                "httpMethod": "POST",
            }
        },
    )
)

​
WebSocket

Receive events in real-time
For reconnect, drain, and reliability semantics, see WebSockets.
const client = new KadoaClient({ apiKey });
const realtime = await client.connectRealtime();

// Subscribe to all events
realtime.onEvent((event) => {
  console.log("Event received:", event.eventType, event.message);
});

// Filter events by type
realtime.onEvent((event) => {
  if (event.eventType === "workflow_finished") {
    console.log("Workflow completed:", event.message);
  }
});

// Handle errors
realtime.onError((error) => {
  console.error("WebSocket error:", error);
});

realtime.close();

client = KadoaClient(KadoaClientConfig(api_key=api_key))
realtime = await client.connect_realtime()

# Subscribe to all events
realtime.on_event(lambda event: print("Event received:", event["eventType"], event["message"]))

# Filter events by type
def handle_filtered(event):
    if event["eventType"] == "workflow_finished":
        print("Workflow completed:", event["message"])

realtime.on_event(handle_filtered)

# Handle errors
realtime.on_error(lambda error: print("WebSocket error:", error))

realtime.close()

​
Subscribe to All Events

await client.notification.setupForWorkflow({
  workflowId: workflowId,
  events: "all",
  channels: { EMAIL: true },
});

​
Reusing Channels

Reference existing channels by ID 
// List channels
const channels = await client.notification.channels.listChannels({});
const webhookChannel = channels.find(c => c.name === "my-webhook");

await client.notification.setupForWorkflow({
  workflowId: newWorkflowId,
  events: ["workflow_data_change"],
  channels: {
    WEBHOOK: { channelId: webhookChannel.id },
  },
});

# List channels
channels = client.notification.channels.list_channels()
webhook_channel = next((c for c in channels if c.name == "my-webhook"), None)

client.notification.setup_for_workflow(
    SetupWorkflowNotificationSettingsRequest(
        workflow_id=new_workflow_id,
        events=["workflow_data_change"],
        channels={
            "WEBHOOK": {"channelId": webhook_channel.id}
        },
    )
)

​
Template-Managed Notifications

When a workflow is linked to a template that includes notifications, the notification settings are managed through the template. Attempting to modify notifications on a template-linked workflow returns a 409 error. Unlink the workflow first, or update the template and apply the change.

​
Setup Notifications via API

​
Step 1: Create Notification Channels

First, create the channels you want to use for notifications. See Email, 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>"]
}

{
  "data": {
    "settings": {
      "id": "settings-123",
      "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>"]
}

{
  "data": {
    "settings": {
      "id": "settings-456",
      "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"]
}

{
  "data": {
    "settings": {
      "id": "<settings-id>",
      "workflowId": "YOUR_WORKFLOW_ID",
      "eventType": "workflow_data_change",
      "eventConfiguration": {},
      "enabled": true,
      "channelIds": ["existing-channel-id", "new-channel-id"]
    }
  }
}
For payload formats, see Email, Webhooks, and WebSockets.