Notifications

Notifications tell you when a workflow finishes, fails, recovers, or finds data changes. They go to email, Slack, webhooks, or WebSockets.

How notifications work

You subscribe a channel to an event. A channel is where the notification goes, such as an email address or a webhook URL. Create the channel before you subscribe it to events. One channel can receive many event types. You configure notifications at two levels:

Team: defaults for every workflow in the team.
Workflow: settings for one workflow. They override the team defaults for the same event type.

Create a channel

Dashboard
SDK & API
MCP

Go to Settings > Notifications.
Under Channels, select Create channel.
Select the channel type: Email, Slack, Webhook, or Websocket.
Fill in the fields for that type. Each type’s page in Channels lists them.
Select Save.

You can also create a channel while you add a notification. In the channel list, select Create new channel.

You need an API key and the SDK: npm install @kadoa/node-sdk or uv add kadoa-sdk.The SDK creates channels for you. setupForWorkflow creates the channel and subscribes it to the events you list in one call.

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"],
    },
  },
});

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

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

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

# Or specify recipients
client.notification.setup_for_workflow(
    SetupWorkflowNotificationSettingsRequest(
        workflow_id="YOUR_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",
    },
  },
});

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_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-destination",
      webhookUrl: "https://api.example.com/webhooks/kadoa",
      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_finished"],
        channels={
            "WEBHOOK": {
                "name": "api-destination",
                "webhookUrl": "https://api.example.com/webhooks/kadoa",
                "httpMethod": "POST",
            }
        },
    )
)

For a WebSocket channel, see Receive events in real time.With the REST API, create the channels first. For request examples, see Email, Webhooks, and WebSockets.

Ask your AI tool, for example:

> Create a webhook notification channel for https://api.example.com/webhooks/kadoa

Your AI tool uses create_notification_channel. It uses list_notification_channels and delete_notification_channel to list or remove channels.

Set team defaults

Dashboard
SDK & API
MCP

Go to Settings > Notifications.
Next to Workspace notifications, select Add notification.
Select an event type, such as Workflow finished.
Select Add a channel, then select a channel or Create new channel.
Select Save changes.

Every workflow in the team uses these defaults unless you override them for that workflow.

Send a POST request to /v5/notifications/settings without a workflowId. The setting applies 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>"]
    }
  }
}

Ask your AI tool, for example:

> Email team@example.com whenever any workflow in my team fails

Your AI tool uses configure_notifications without a workflow, which sets a team default.

Set notifications for one workflow

Dashboard
SDK & API
MCP

You can set notifications while you create a workflow or later.While you create the workflow: in the setup prompt, select Notifications. Then select one or more channels, or select Create channel. Kadoa applies the selection to data change notifications when it creates the workflow.After you create the workflow:

Open your workflow and select the Notifications tab.
Select Add notification.
Select an event type.
Select Add a channel, then select a channel or Create new channel.
Select Save changes.

Workflow settings override team settings for the same event type.

setupForWorkflow subscribes a workflow to events and creates the channels it needs.

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",
            }
        },
    )
)

The SDK reuses existing channels with the same name. Running setup multiple times won’t create duplicates.

To subscribe to every event, pass events: "all":

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

To reuse an existing channel, reference it by ID:

const workflowId = "YOUR_WORKFLOW_ID";

// List channels
const channels = await client.notification.channels.listChannels({});
const webhookChannel = channels.find((channel) => channel.name === "my-webhook");

if (!webhookChannel) {
  throw new Error("Webhook channel not found");
}

if (!webhookChannel.id) {
  throw new Error("Webhook channel has no ID");
}

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

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

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

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

if webhook_channel is None:
    raise RuntimeError("Webhook channel not found")

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

With the REST API, send a POST request to /v5/notifications/settings with a workflowId:

// 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>"]
    }
  }
}

To add channels to an existing setting, send 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"]
    }
  }
}

Ask your AI tool, for example:

> Set up a webhook notification on my 'Product Monitor' workflow that triggers on data changes, sending to https://your-server.com/webhook

Your AI tool uses configure_notifications, which creates the channel and the setting in one step. It uses list_notification_settings and delete_notification_setting to review or remove settings.

Filter data change alerts

You choose which data changes trigger a workflow_data_change notification. Kadoa sends this event after it detects changes with the change detection rules. You set these filters per workflow in the dashboard:

Track fields: the fields to watch. All fields by default.
Filters: conditions on field values. Kadoa notifies only when values match them.
Type of change: the kinds of change that trigger a notification. All three are on by default.
- Updated: an existing record changed. This needs at least one key field. Without one, a changed record arrives as one removal and one addition.
- Added: a new record appeared.
- Removed: a record disappeared.

The filters need a schema. If the workflow has none, the tab shows “Add a schema to track changes.”

Open your workflow and select the Notifications tab.
Select the Data changes notification. To add one, select Add notification > Data changes, then add a channel.
Under Track fields, keep all fields or select Select fields to track and pick fields.
Under Filters, add conditions.
Under Type of change, select Updated, Added, or Removed.
Select Save changes.

An expanded Data changes notification with the Track fields, Filters, Type of change, and Notification content rows

Filter operators

Combine conditions with:

Any (OR): Notify if any condition matches
All (AND): Notify only if all conditions match

Operators:

Operator	Description	Example
`contains`	Field value contains text	title contains “sale”
`does not contain`	Field value excludes text	title does not contain “expired”
`equals`	Exact match	status equals “active”
`does not equal`	Does not match	status does not equal “draft”
`greater than`	Numeric comparison	price greater than 100
`less than`	Numeric comparison	stock less than 10
`before`	Date is before value	published before 2025-01-01
`after`	Date is after value	published after 2025-01-01
`in the last`	Date within N days	published in the last 7 days
`is empty`	Field has no value	description is empty
`is not empty`	Field has a value	price is not empty

Date filters

Use before, after, or in the last operators to filter changes by date. Use this for news feeds or other content where only recent items matter.

Your data must include a date field for date filtering to work.

Supported date formats:

ISO: 2025-01-15 (recommended)
US/EU: 01/15/2025, 15/01/2025
Month names: Jan 15, 2025
Timestamps: 2025-01-15T10:30:00Z

Choose what notifications contain

Data change and Workflow finished notifications can carry extra content, such as an AI summary or a CSV file. Set team defaults, then override them for one workflow if needed. For what each option does, see Notification content. You set notification content in the dashboard. For the team:

Go to Settings > Notifications.
Below Workspace notifications, find the Data changes or Workflow finished section.
Turn AI summary, Changed records, or CSV attachment on or off. Each change saves right away.

Team notification content settings with switches for AI summary, Changed records, and CSV attachment under Data changes, and CSV attachment under Workflow finished

For one workflow:

Open your workflow, select the Notifications tab, and select the notification.
In the Notification content row, open the content menu.
Turn off Use workspace defaults.
Turn each option on or off.
Select Save changes.

Send a test

You send tests from the dashboard to check that a channel receives notifications.

Open a saved notification in Settings > Notifications or on the workflow’s Notifications tab.
Select Send test. The button appears when the notification has a channel and no unsaved changes.
Check your channel for the test notification. Tests use sample data, not your records.

A Workflow finished notification with the Send test button highlighted

Receive events in real time

With the SDK, you connect to the WebSocket channel and receive events as they happen. 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.type, event.message);
});

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

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

realtime.close();

import asyncio
from collections.abc import Mapping

from kadoa_sdk import KadoaClient, KadoaClientConfig

async def main() -> None:
    client = KadoaClient(KadoaClientConfig(api_key="YOUR_API_KEY"))
    realtime = await client.connect_realtime()

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

    # Filter events by type
    def handle_filtered(event: Mapping[str, object]) -> None:
        if event["type"] == "workflow_finished":
            print("Workflow completed:", event["message"])

    realtime.on_event(handle_filtered)

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

    try:
        await asyncio.Event().wait()
    finally:
        await realtime.close_async()

asyncio.run(main())

Template-managed notifications

Notifications can be part of a template. When a workflow is linked to a template that includes notifications, the template manages the workflow’s notification settings. The workflow’s Notifications tab shows them read-only. To change them, update the template and apply the change, or unlink the workflow from the template. With the SDK or API, changing notifications on a template-linked workflow returns a 409 error.

Event types

Event	Dashboard label	Description
`workflow_finished`	Workflow finished	Workflow completed successfully
`workflow_failed` / `workflow_recovered`	Workflow health	Workflow failed or recovered. See Workflow health.
`workflow_data_change`	Data changes	Data changes detected (change detection rules)
`workflow_data_quality_change`	Data quality issues	Data quality issues of a run change. Formerly `workflow_validation_anomaly_change`.

The same events can also start another workflow. See Triggers.

Workflow health

Subscribing to Workflow health gives you failure and recovery notifications for your workflows.

Failure: when a run fails, you receive a workflow_failed event with the error reason and a suggested action.
Recovery: when the workflow succeeds after a failure, you receive a workflow_recovered event.

If you also subscribe to Workflow finished, the workflow_finished event replaces recovery notifications for scheduled workflows. You don’t receive both for the same run. For real-time monitors, Kadoa always sends workflow_recovered when the monitor comes back online, whatever your other subscriptions.

System events

These events are automatic. You can’t configure them.

Event	Description
`workflow_sample_finished`	Preview data ready. Sent to the workflow author only, by email.
`workflow_export_completed`	A delivery to a data destination failed. Despite the name, Kadoa sends this notification only on failure.

Channels

Channel	Description
Email	Sends to your account email or a list of addresses
Slack	Posts to a Slack channel
Webhook	Sends an HTTP request to your endpoint
WebSocket	Streams events to a client you run

Each channel has its own payload format. See the channel pages for payload formats and examples.

Notification content

Each option applies per event type. To change them, see Choose what notifications contain.

Option	Events	Default	Where it appears
AI summary	Data changes	Off	Email shows it above the changed records. Webhook and WebSocket payloads carry it in `summary`.
Changed records	Data changes	On	Email lists the records. Webhook payloads carry them in `differences`. WebSocket payloads always include `differences`, even when this option is off.
CSV attachment	Data changes, Workflow finished	Off	Email only

AI summary

The AI summary is one or two sentences that say what changed, for example: Prices changed on 65 SSDs. The Samsung 990 PRO 2TB dropped from “423.75” to “408.95”. If people read the alerts, turn it on. If only code reads them, leave it off.

Kadoa writes the summary once per change. Email, webhook, and WebSocket notifications carry the same text.
It adds about one second to the notification.
When the AI summary is off, summary is null.
If a summary does not match the changed records, Kadoa drops it. The notification then goes out without one, and summary is null.

CSV attachment

Email attaches the CSV when it is small enough. Larger files arrive as a download link. The link is always included.

Change detection: the rules that decide what counts as a data change
Templates: share notification settings across workflows
Contact support for help with setup

Get started

Concepts

Security & Compliance

Build workflows

Templates

Monitor & alert

MCP

Integrations

Administration

How notifications work

Create a channel

Email

Slack

Webhook

Set team defaults

Set notifications for one workflow

Filter data change alerts

Filter operators

Date filters

Choose what notifications contain

Send a test

Receive events in real time

Template-managed notifications

Event types

Workflow health

System events

Channels

Notification content

AI summary

CSV attachment

​How notifications work

​Create a channel

​Email

​Slack

​Webhook

​Set team defaults

​Set notifications for one workflow

​Filter data change alerts

​Filter operators

​Date filters

​Choose what notifications contain

​Send a test

​Receive events in real time

​Template-managed notifications

​Event types

​Events you can subscribe to

​Workflow health

​System events

​Channels

​Notification content

​AI summary

​CSV attachment

​Related

How notifications work

Create a channel

Email

Slack

Webhook

Set team defaults

Set notifications for one workflow

Filter data change alerts

Filter operators

Date filters

Choose what notifications contain

Send a test

Receive events in real time

Template-managed notifications

Event types

Events you can subscribe to

Workflow health

System events

Channels

Notification content

AI summary

CSV attachment

Related