> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kadoa.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks

> Receive HTTP notifications when workflow events occur

> [!NOTE]
>
> Your webhook endpoint must be publicly accessible.

## Setup

```typescript title="Node SDK" theme={null}
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://api.example.com/webhooks/kadoa",
      httpMethod: "POST",
    },
  },
});
```

```python title="Python SDK" theme={null}
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://api.example.com/webhooks/kadoa",
                "httpMethod": "POST",
            }
        },
    )
)
```

For the REST API, see [Create notification channel](https://docs.kadoa.com/api-reference/notifications/create-notification-channel.md).

### Dashboard Setup

1. Go to **Settings > Notifications**
2. Under **Channels**, select **Create channel** and choose **Webhook**
3. Enter your endpoint URL
4. Save changes

![Webhook setup](https://mintcdn.com/kadoa/J2BP2lmQhWDWhIB8/images/notifications/webhook/webhook-ui.png?fit=max\&auto=format\&n=J2BP2lmQhWDWhIB8\&q=85\&s=37a882d09c705f539d6f043dad6f86a8)

## Authentication

Add custom headers for webhook authentication:

```json theme={null}
// POST /v5/notifications/channels
{
  "channelType": "WEBHOOK",
  "name": "Authenticated Webhook",
  "config": {
    "webhookUrl": "https://api.example.com/webhooks/kadoa",
    "httpMethod": "POST",
    "auth": {
      "type": "HEADER",
      "headers": {
        "Authorization": "Bearer your-secret-token",
        "X-Custom-Header": "custom-value"
      }
    }
  }
}
```

## Request Format

Every webhook request includes:

| Header | Description |
| - | - |
| `Content-Type` | `application/json` |
| `X-Kadoa-Event` | Event type (e.g., `workflow_data_change`) |

## Payload Reference

All payloads follow this structure:

```json theme={null}
{
  "eventType": "event_name",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": { /* event-specific data */ }
}
```

```json title="workflow_data_change" theme={null}
{
  "eventType": "workflow_data_change",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "change_123",
    "workflowId": "wf_123",
    "data": [
      { "id": "record-1", "name": "Product A", "price": 29.99 }
    ],
    "differences": [
      {
        "type": "changed",
        "fields": [
          { "key": "price", "value": 29.99, "previousValue": 24.99 }
        ]
      },
      {
        "type": "added",
        "fields": [
          { "key": "id", "value": "record-2" },
          { "key": "name", "value": "New Product" }
        ]
      }
    ],
    "url": "https://monitored-page.com",
    "createdAt": "2025-01-15T10:30:00Z",
    "summary": "Prices changed on 1 product and 1 new product appeared. Product A rose from \"24.99\" to \"29.99\".",
    "metadata": {
      "workflowName": "Product Monitor",
      "tags": ["pricing"]
    }
  }
}
```

```json title="workflow_finished" theme={null}
{
  "eventType": "workflow_finished",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "id": "wf_123",
    "jobId": "job_456",
    "source": "scheduler"
  }
}
```

```json title="workflow_failed" theme={null}
{
  "eventType": "workflow_failed",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "workflowId": "wf_123",
    "workflowName": "Product Monitor",
    "source": "Product Monitor",
    "sourceUrl": "https://monitored-page.com",
    "url": "https://monitored-page.com",
    "reason": "Access blocked by bot protection",
    "action": "No action needed. We'll email you when the workflow recovers."
  }
}
```

```json title="workflow_recovered" theme={null}
{
  "eventType": "workflow_recovered",
  "timestamp": "2025-01-15T10:45:00Z",
  "data": {
    "workflowId": "wf_123",
    "workflowName": "Product Monitor",
    "source": "Product Monitor",
    "sourceUrl": "https://monitored-page.com",
    "url": "https://monitored-page.com"
  }
}
```

```json title="workflow_data_quality_change" theme={null}
{
  "eventType": "workflow_data_quality_change",
  "timestamp": "2025-01-15T10:30:00Z",
  "data": {
    "workflowId": "wf_123",
    "jobId": "job_456",
    "previousJobId": "job_455",
    "workflowName": "Product Monitor",
    "createdAt": "2025-01-15T10:30:00Z",
    "dataQualityIssues": { "current": 4, "previous": 2 },
    "rowViolations": { "current": 4, "previous": 2 },
    "currentSummary": {
      "schemaValidation": {
        "rowViolationCount": 4,
        "rules": null,
        "columns": [
          { "name": "price", "violations": [{ "kind": "ROW_COUNT", "ruleKey": "presence", "count": 4 }] }
        ]
      },
      "completeness": { "score": 90, "actualRowCount": 48, "expectedRowCount": 52, "signalCount": 2, "cappedByLimit": false },
      "semanticPlausibility": { "score": 98, "flaggedColumns": [] }
    },
    "previousSummary": {
      "schemaValidation": {
        "rowViolationCount": 2,
        "rules": null,
        "columns": [
          { "name": "price", "violations": [{ "kind": "ROW_COUNT", "ruleKey": "presence", "count": 2 }] }
        ]
      },
      "completeness": { "score": 96, "actualRowCount": 50, "expectedRowCount": 52, "signalCount": 2, "cappedByLimit": false },
      "semanticPlausibility": { "score": 98, "flaggedColumns": [] }
    }
  }
}
```

`workflow_data_change` `data` holds the records of the run that produced the change. If they exceed the 50 MB notification limit, `data` is an empty array and `dataOmitted` is set: `reason` is `PAYLOAD_TOO_LARGE`, and `message` names the API call for this run. Fetch the records with `GET /v4/workflows/{workflowId}/data?runId={jobId}`. Branch on `reason`; the `message` text can change.

`workflow_data_change` `summary` is the [AI summary](https://docs.kadoa.com/docs/notifications.md#ai-summary) of the change. It is `null` when the AI summary option is off. When the **Changed records** option is off, `differences` is an empty array.

`workflow_failed` fields: required `workflowId`, `source`, `reason`, `action`; optional `workflowName`, `sourceUrl`, `url`.

`workflow_recovered` fields: required `workflowId`, `workflowName`, `source`; optional `sourceUrl`, `url`.

| Event | Description |
| - | - |
| `workflow_data_change` | Monitored data changes. Difference types: `changed`, `added`, `removed` |
| `workflow_finished` | Workflow completes successfully |
| `workflow_failed` | Workflow fails. Includes `reason` and a human-readable `action`. |
| `workflow_recovered` | Workflow recovers after failure. Sent via `workflow_failed` subscription; suppressed if `workflow_finished` is also configured. |
| `workflow_data_quality_change` | Data quality issues of a run change. Formerly `workflow_validation_anomaly_change`. |

## Error Handling

Kadoa makes up to 3 attempts to deliver each webhook. Each attempt times out after 30 seconds.

| Attempt | Wait before it |
| - | - |
| 1st | None |
| 2nd | 1 second |
| 3rd | 2 seconds |

Return a `2xx` status code to acknowledge receipt.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.