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

# Notifications

> Set up alerts for task executions, resource changes, and more — delivered to Slack, Discord, email, PagerDuty, and 100+ other services.

DataRaven uses [Apprise](https://github.com/caronc/apprise) under the hood to deliver notifications
to virtually any service you already use. Configure a notification once, and DataRaven will alert
you whenever the events you care about occur.

## How It Works

<Steps>
  <Step title="Choose an event type">
    Pick which event should trigger the notification (e.g., task execution failed).
  </Step>

  <Step title="Provide an Apprise URL">
    Each notification service has a unique URL format that contains your credentials or webhook
    token.
  </Step>

  <Step title="Optionally filter and customize">
    Narrow which events match using filters, and customize the message with a Jinja2 template.
  </Step>

  <Step title="Test and enable">
    Use the **Send Test** button to verify delivery, then enable the notification.
  </Step>
</Steps>

## Quick Setup

Quick Setup lets you create multiple notification configs at once — one per event type — all sharing
the same Apprise URL. This is the fastest way to get comprehensive alerting for a single
destination like a Slack channel or Discord webhook.

<Steps>
  <Step title="Navigate to Quick Setup">
    Go to **Notifications** and click **Quick Setup**.
  </Step>

  <Step title="Enter a name and Apprise URL">
    Provide a name prefix (e.g., "Slack Alerts") and your Apprise URL. Each notification config will
    be named **"\{prefix} - \{Event Name}"** (e.g., "Slack Alerts - Execution Failed").
  </Step>

  <Step title="Select event types">
    Check the event types you want notifications for. Use the group checkboxes to select entire
    categories, or **Select All** for full coverage.
  </Step>

  <Step title="Create">
    Click **Create** to bulk-create all selected configs in a single request. Each config gets
    a sensible default message template that you can customize later.
  </Step>
</Steps>

<Tip>
  After Quick Setup, each notification config is fully independent — you can edit individual configs
  to add event filters, change templates, or disable specific ones without affecting the others.
</Tip>

### Quick Setup via API

You can also bulk-create notifications programmatically using the
[Bulk Create endpoint](/api-reference/notifications/bulk-create-notifications):

```bash theme={"theme":{"light":"github-light","dark":"poimandres"}}
curl -X POST https://api.dataraven.io/v1/teams/{team_id}/notifications/bulk \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Slack Alerts",
    "apprise_url": "slack://tokenA/tokenB/tokenC",
    "event_types": [
      "task_execution_started",
      "task_execution_completed",
      "task_execution_failed",
      "task_execution_cancelled"
    ]
  }'
```

This creates one notification config per event type. The response includes all created configs with
their IDs, vault references, and default templates.

## Apprise URLs

Every notification service is configured through a single URL string. Apprise supports **100+
services** — see the [full list on the Apprise docs](https://appriseit.com/services/).

### Popular Services

<CodeGroup>
  ```text Slack theme={"theme":{"light":"github-light","dark":"poimandres"}}
  slack://tokenA/tokenB/tokenC
  ```

  ```text Discord theme={"theme":{"light":"github-light","dark":"poimandres"}}
  discord://webhook_id/webhook_token
  ```

  ```text Microsoft Teams theme={"theme":{"light":"github-light","dark":"poimandres"}}
  msteams://TokenA/TokenB/TokenC
  ```

  ```text Email (Gmail) theme={"theme":{"light":"github-light","dark":"poimandres"}}
  mailto://user:password@gmail.com
  ```

  ```text PagerDuty theme={"theme":{"light":"github-light","dark":"poimandres"}}
  pagerduty://integration_key@routing_key
  ```

  ```text Telegram theme={"theme":{"light":"github-light","dark":"poimandres"}}
  tgram://bot_token/chat_id
  ```
</CodeGroup>

<Tip>
  Refer to the [Apprise wiki](https://github.com/caronc/apprise/wiki) for the exact URL format and
  required tokens for your service.
</Tip>

## Event Types

DataRaven supports **18 event types** organized into five categories:

<Tabs>
  <Tab title="Execution Events">
    Events fired during task execution lifecycle.

    | Event Type                 | Fires When                         |
    | -------------------------- | ---------------------------------- |
    | `task_execution_started`   | An execution begins                |
    | `task_execution_completed` | An execution finishes successfully |
    | `task_execution_failed`    | An execution encounters an error   |
    | `task_execution_cancelled` | An execution is cancelled          |
  </Tab>

  <Tab title="Task Events">
    Events fired when tasks are created, modified, or removed.

    | Event Type            | Fires When                     |
    | --------------------- | ------------------------------ |
    | `task_created`        | A new task is created          |
    | `task_updated`        | A task's configuration changes |
    | `task_deleted`        | A task is deleted              |
    | `task_status_changed` | A task is enabled or disabled  |
  </Tab>

  <Tab title="Secret Events">
    Events fired when secrets are managed.

    | Event Type       | Fires When              |
    | ---------------- | ----------------------- |
    | `secret_created` | A new secret is created |
    | `secret_updated` | A secret is updated     |
    | `secret_deleted` | A secret is deleted     |
  </Tab>

  <Tab title="Location Events">
    Events fired when storage locations change.

    | Event Type         | Fires When                |
    | ------------------ | ------------------------- |
    | `location_created` | A new location is created |
    | `location_updated` | A location is updated     |
    | `location_deleted` | A location is deleted     |
  </Tab>

  <Tab title="API Key Events">
    Events fired when API keys are managed.

    | Event Type        | Fires When               |
    | ----------------- | ------------------------ |
    | `api_key_created` | A new API key is created |
    | `api_key_rotated` | An API key is rotated    |
    | `api_key_revoked` | An API key is revoked    |
    | `api_key_deleted` | An API key is deleted    |
  </Tab>
</Tabs>

## Event Filters

Event filters let you narrow which events trigger the notification. Filters are a JSON object where
**all conditions must match** (AND logic). Leave empty (`{}`) to match all events of the selected
type.

### Filter Rules

* **Exact match** — `{"trigger": "scheduled"}` matches only scheduled triggers
* **Any-of match** — `{"status": ["failed", "completed"]}` matches if the value is any item in the
  array
* **Boolean match** — `{"is_dry_run": false}` matches only real executions
* **Multiple conditions** — `{"trigger": "scheduled", "is_dry_run": false}` requires both to match

### Examples by Event Type

<CodeGroup>
  ```json Execution Filters theme={"theme":{"light":"github-light","dark":"poimandres"}}
  // Only failed and completed executions
  {"status": ["failed", "completed"]}

  // Only scheduled triggers (not manual)
  {"trigger": "scheduled"}

  // Only real executions (not dry runs)
  {"is_dry_run": false}
  ```

  ```json Task Filters theme={"theme":{"light":"github-light","dark":"poimandres"}}
  // A specific task by name
  {"name": "my-task"}

  // Only sync tasks
  {"task_type": "sync"}

  // Only enabled tasks
  {"status": "enabled"}
  ```

  ```json Secret Filters theme={"theme":{"light":"github-light","dark":"poimandres"}}
  // A specific secret
  {"name": "my-secret"}

  // Secrets of a specific type
  {"secret_type": "s3"}
  ```

  ```json Location Filters theme={"theme":{"light":"github-light","dark":"poimandres"}}
  // Azure blob locations only
  {"location_type": "azure_blob"}

  // A specific region
  {"region": "us-east-1"}
  ```

  ```json API Key Filters theme={"theme":{"light":"github-light","dark":"poimandres"}}
  // A specific API key
  {"name": "my-api-key"}

  // A specific key ID
  {"key_id": "AbCdEf123456"}
  ```
</CodeGroup>

## Message Templates

Notifications use [Jinja2 templates](https://jinja.palletsprojects.com/) to format the message body.
Each event type exposes different variables. If you don't provide a custom template, DataRaven uses
a sensible default.

### Available Variables

<Tabs>
  <Tab title="Execution Events">
    | Variable           | Description                           |
    | ------------------ | ------------------------------------- |
    | `task_name`        | Name of the task                      |
    | `execution_number` | Sequential execution number           |
    | `status`           | Current execution status              |
    | `duration_seconds` | Execution duration (completed events) |
    | `error_message`    | Error details (failed events)         |
  </Tab>

  <Tab title="Task Events">
    | Variable      | Description                    |
    | ------------- | ------------------------------ |
    | `name`        | Task name                      |
    | `description` | Task description               |
    | `status`      | Task status (enabled/disabled) |
  </Tab>

  <Tab title="Secret Events">
    | Variable | Description |
    | -------- | ----------- |
    | `name`   | Secret name |
  </Tab>

  <Tab title="Location Events">
    | Variable        | Description                             |
    | --------------- | --------------------------------------- |
    | `name`          | Location name                           |
    | `location_type` | Storage type (e.g., `s3`, `azure_blob`) |
  </Tab>

  <Tab title="API Key Events">
    | Variable           | Description                           |
    | ------------------ | ------------------------------------- |
    | `name`             | API key name                          |
    | `created_by_email` | Email of the user who created the key |
    | `expires_at`       | Expiration date (or `Never`)          |
    | `created_at`       | Creation timestamp                    |
    | `rotated_at`       | Rotation timestamp (rotated events)   |
  </Tab>
</Tabs>

### Default Templates

Here are the built-in templates DataRaven uses when you don't specify a custom one:

<CodeGroup>
  ```text Execution Started theme={"theme":{"light":"github-light","dark":"poimandres"}}
  🚀 Task execution started

  Task: {{task_name}}
  Execution: #{{execution_number}}
  Status: {{status}}
  ```

  ```text Execution Completed theme={"theme":{"light":"github-light","dark":"poimandres"}}
  ✅ Task execution completed

  Task: {{task_name}}
  Execution: #{{execution_number}}
  Duration: {{duration_seconds}}s
  ```

  ```text Execution Failed theme={"theme":{"light":"github-light","dark":"poimandres"}}
  🚨 Task execution failed

  Task: {{task_name}}
  Execution: #{{execution_number}}
  Error: {{error_message}}
  ```

  ```text Task Created theme={"theme":{"light":"github-light","dark":"poimandres"}}
  📝 New task created

  Name: {{name}}
  Description: {{description}}
  ```

  ```text Location Created theme={"theme":{"light":"github-light","dark":"poimandres"}}
  📍 New location created: {{name}} ({{location_type}})
  ```

  ```text API Key Created theme={"theme":{"light":"github-light","dark":"poimandres"}}
  🔑 API key created

  Name: {{name}}
  Created by: {{created_by_email}}
  Expires: {{expires_at or 'Never'}}
  Created: {{created_at}}
  ```

  ```text API Key Rotated theme={"theme":{"light":"github-light","dark":"poimandres"}}
  🔑 API key rotated

  Name: {{name}}
  Rotated by: {{created_by_email}}
  Rotated at: {{rotated_at}}
  ```
</CodeGroup>

You can customize templates with any valid Jinja2 syntax — conditionals, default values, formatting,
etc.

```jinja theme={"theme":{"light":"github-light","dark":"poimandres"}}
🚨 ALERT: {{task_name}} failed (Execution #{{execution_number}})

{% if error_message %}
Error: {{error_message}}
{% else %}
No error details available.
{% endif %}
```

## Testing Notifications

Before relying on a notification in production, use the **Send Test** button in the admin UI. This
sends a sample notification using your configured Apprise URL and message template so you can verify
delivery without waiting for a real event.

<Note>
  Test notifications use placeholder data for template variables (e.g., `task_name` = "Test Task").
  The actual notification will contain real event data.
</Note>

## Security

<Warning>
  Apprise URLs contain sensitive credentials — webhook tokens, API keys, passwords. DataRaven
  **never** stores these in plain text or returns them in API responses.
</Warning>

* Apprise URLs are encrypted and stored in **AWS SSM Parameter Store**
* API responses include only a vault reference ID (`apprise_vault_secret_id`), never the URL itself
* URLs are only decrypted internally when sending a notification

## Tier Limits

| Plan     | Notification Configs |
| -------- | -------------------- |
| **Free** | 1                    |
| **Pro**  | 25                   |

Need more? [Upgrade your plan](https://app.dataraven.io) from the billing page.

## Common Patterns

<CardGroup cols={2}>
  <Card title="Alert on all failures" icon="triangle-exclamation">
    **Event type:** `task_execution_failed`
    **Filters:** `{}`
    **Result:** Get notified whenever any task fails.
  </Card>

  <Card title="Slack on scheduled completions" icon="clock">
    **Event type:** `task_execution_completed`
    **Filters:** `{"trigger": "scheduled"}`
    **Result:** Notify Slack when scheduled tasks finish (ignore manual runs).
  </Card>

  <Card title="PagerDuty for critical failures" icon="bell">
    **Event type:** `task_execution_failed`
    **Filters:** `{"is_dry_run": false}`
    **Result:** Page on-call when real (non-dry-run) executions fail.
  </Card>

  <Card title="Audit secret changes" icon="key">
    **Event type:** `secret_created`, `secret_updated`, `secret_deleted`
    **Filters:** `{}`
    **Result:** Track all secret lifecycle events for compliance.
  </Card>

  <Card title="Monitor API key activity" icon="key">
    **Event type:** `api_key_created`, `api_key_rotated`, `api_key_revoked`, `api_key_deleted`
    **Filters:** `{}`
    **Result:** Track all API key lifecycle events for security auditing.
  </Card>
</CardGroup>

<Tip>
  You can create multiple notification configs for the same event type with different filters and
  destinations — for example, send failures to both Slack and PagerDuty.
</Tip>