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

# Configure Slack Webhook

> Configure Slack notifications for job failures

## Overview

Configure a Slack incoming webhook to receive notifications when jobs fail. You can choose to receive **all** failure notifications, **errors only** (technical failures), or **warnings only** (content issues like private/unavailable videos). The webhook URL is stored securely and encrypted at rest.

## Header Parameters

<ParamField header="x-api-key" type="string" required>
  Your API key for authentication
</ParamField>

## Request

<ParamField body="webhook_url" type="string" required>
  Slack incoming webhook URL. Must start with `https://hooks.slack.com/services/`.
</ParamField>

<ParamField body="notify_level" type="string" default="all">
  Controls which failure types trigger a Slack notification:

  * `all` — Both errors and warnings (default)
  * `errors_only` — Only technical failures (rate limits, bot detection, connection errors)
  * `warnings_only` — Only content issues (private video, members-only, geo-blocked, unavailable)
</ParamField>

## Examples

<CodeGroup>
  ```bash All notifications (default) theme={null}
  curl -X POST "https://api.tornadoapi.io/user/slack" \
    -H "x-api-key: sk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "webhook_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX"
    }'
  ```

  ```bash Errors only (skip warnings) theme={null}
  curl -X POST "https://api.tornadoapi.io/user/slack" \
    -H "x-api-key: sk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "webhook_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
      "notify_level": "errors_only"
    }'
  ```

  ```bash Warnings only (content issues) theme={null}
  curl -X POST "https://api.tornadoapi.io/user/slack" \
    -H "x-api-key: sk_your_api_key" \
    -H "Content-Type: application/json" \
    -d '{
      "webhook_url": "https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX",
      "notify_level": "warnings_only"
    }'
  ```
</CodeGroup>

## Success Response

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "message": "Slack webhook configured successfully",
    "configured": true,
    "notify_level": "all"
  }
  ```
</ResponseExample>

## Error Responses

<ResponseExample>
  ```json 400 Bad Request theme={null}
  {
    "error": "Slack webhook URL must start with https://hooks.slack.com/services/"
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "error": "Invalid notify_level. Must be 'all', 'errors_only', or 'warnings_only'"
  }
  ```

  ```json 401 Unauthorized theme={null}
  {
    "error": "Invalid API Key"
  }
  ```

  ```json 503 Service Unavailable theme={null}
  {
    "error": "Slack webhook configuration is temporarily unavailable"
  }
  ```
</ResponseExample>

<Note>
  If you already have a Slack webhook configured, calling this endpoint again will replace the existing webhook and notify level.
</Note>

## Notification Format

When a job fails, Tornado sends a Slack message with a colored attachment:

* **Red** (`:x:`) for technical errors (rate limits, connection issues, bot detection)
* **Orange** (`:warning:`) for content warnings (private video, members-only, geo-blocked, unavailable)

The message includes the **Job ID**, a **sanitized error category** (no internal infrastructure details are exposed), and the **source URL**.

## Notify Level Reference

| Level           | Errors (red) | Warnings (orange) |
| --------------- | :----------: | :---------------: |
| `all`           |       ✓      |         ✓         |
| `errors_only`   |       ✓      |         ✗         |
| `warnings_only` |       ✗      |         ✓         |

### What counts as an error vs warning?

| Type                  | Examples                                                                                                              |
| --------------------- | --------------------------------------------------------------------------------------------------------------------- |
| **Error** (technical) | Bot detection, rate limited, connection error, upload failed, processing failed                                       |
| **Warning** (content) | Private video, members-only, video unavailable, age-restricted, geo-blocked, channel terminated, copyright restricted |

<Note>
  Only failed jobs trigger Slack notifications. Completed, pending, and processing jobs do not send any notification to Slack.
</Note>