Skip to main content
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.

​
Workflow Events

  • Data changes - When monitored data changes are detected
  • Workflow finished - When a workflow completes successfully
  • Workflow failed - When a workflow fails during execution
  • Data quality issues - When new data validation issues detected

​
Configure notifications with API

First, create the channels you want to use for notifications. See Webhooks and WebSockets for channel creation examples. Then, subscribe to events by sending a POST request to /v5/notifications/settings.
  • Workspace-Level Subscription:
// POST /v5/notifications/settings
{
  "eventType": "workflow_finished",
  "eventConfiguration": {},
  "enabled": true,
  "channelIds": ["<channel-id>"]
}
  • Workflow-Level Subscription:
// POST /v5/notifications/settings
{
  "workflowId": "<your-workflow-id>",
  "eventType": "workflow_data_change",
  "eventConfiguration": {},
  "enabled": true,
  "channelIds": ["<channel-id>"]
}

​
Updating Existing Settings

To add more channels to an 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.
When tracking data changes, you may want to also configure monitoring.
Configuration: 
{
  "workflowId": "<workflow-id>",
  "eventType": "workflow_data_change",
  "eventConfiguration": {},
  "enabled": true,
  "channelIds": ["webhook-channel-id", "websocket-channel-id"]
}

​
workflow_finished

Triggered when a workflow completes successfully. Configuration: 
{
  "eventType": "workflow_finished",
  "eventConfiguration": {},
  "enabled": true,
  "channelIds": ["slack-channel-id", "email-channel-id"]
}

​
Configure notifications with UI

  1. Workspace-level settings - Configure in team settings
Screenshot of workspace notification settings
  1. Workflow-level settings - Configure in individual workflow settings
Screenshot of workflow notification settings

​
Testing Notifications

After configuring notifications, you can test your settings using the test endpoint. This allows you to verify that your channels are working correctly and that notifications will be delivered as expected.

​
Test Endpoint

Use the test endpoint to send a mock notification event: 
// POST /v5/notifications/test
{
  "eventType": "workflow_finished",
  "workflowId": "optional-workflow-id"
}

​
Testing in the UI

You can also test notifications directly from the UI:
  1. Navigate to the Notifications page
  2. Select an event type
  3. Configure your channels
  4. Click the “Test” button to send a test notification
Screenshot of test notifications button The test will send a mock event to all configured channels for that event type.

​
Complete 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"]
}

​
Best Practices

​
1. Start with Workflow-Level Settings

For workflows, create specific settings with immediate notifications and multiple channels.

​
2. Choose the Right Channels

  • Email - For team notifications and alerts
  • Webhooks - For integration with external systems
  • WebSockets - For receiving fastest alerts
Screenshot of notification channel selection

​
Troubleshooting

​
Common Notification Issues and Configuration Problems

  1. Check that the settings are enabled
  2. Verify that the event type is supported
  3. Ensure the linked channels are valid
  4. If you receive the error “A notification settings with this event type already exists” on POST request, please use the PUT endpoint instead.

​
Testing Your Configuration

If notifications aren’t working as expected, use the test endpoint to verify your setup:
  1. Test individual channels - Use the test endpoint to send a mock event
  2. Check channel settings - Verify webhook URLs, email addresses, etc.
  3. Review notification logs - Check the logs to see if events are being processed
  4. Verify authentication - Ensure API keys and credentials are correct

​
Common Issues

  • Webhook timeouts - Ensure your webhook endpoint responds quickly
  • Email delivery - Check spam folders and email server settings
  • Invalid event types - Use only supported event types from the API
  • Missing permissions - Ensure your API key has the required permissions
⌘I