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

# Webhooks

> Send real-time notifications to Slack or Microsoft Teams when data quality events occur.

## Overview

ORCA webhooks deliver real-time notifications to your team's communication channels when important data quality events happen. Configure webhooks to alert your team about quality drops, GDPR detections, new issues, scan failures, and contract violations.

## Supported platforms

| Platform            | Payload format                                        |
| ------------------- | ----------------------------------------------------- |
| **Slack**           | [Block Kit](https://api.slack.com/block-kit) messages |
| **Microsoft Teams** | [Adaptive Cards](https://adaptivecards.io/) v1.4      |

## Setting up a webhook

<Steps>
  <Step title="Create an incoming webhook in your platform">
    **Slack:** Go to your Slack workspace settings, create a new Incoming Webhook, and copy the webhook URL.

    **Microsoft Teams:** In your Teams channel, add an Incoming Webhook connector and copy the URL.
  </Step>

  <Step title="Add the webhook in ORCA">
    Navigate to **Settings > Webhooks** and click **Add webhook**.
  </Step>

  <Step title="Configure the webhook">
    * **Name** -- a descriptive label (e.g. "Data team alerts")
    * **Platform** -- `slack` or `teams`
    * **Webhook URL** -- the HTTPS URL from step 1
    * **Event types** -- select which events trigger notifications
  </Step>

  <Step title="Test the connection">
    Click **Test** to send a test message to your channel. Verify the message appears before saving.
  </Step>
</Steps>

<Warning>
  Webhook URLs must use HTTPS. Internal or private IP addresses are blocked for SSRF protection.
</Warning>

## Event types

Select which events trigger webhook notifications:

| Event type           | Description                                         |
| -------------------- | --------------------------------------------------- |
| `quality_drop`       | A dataset's quality score has decreased             |
| `quality_improved`   | A dataset's quality score has improved              |
| `gdpr_detected`      | GDPR-sensitive data (PII) was detected in an upload |
| `new_issue`          | A new data quality issue was found                  |
| `scan_failure`       | A scheduled data source scan failed                 |
| `contract_violation` | A data contract rule was violated                   |

By default, new webhooks subscribe to `quality_drop`, `gdpr_detected`, `new_issue`, and `scan_failure`.

## Payload format

### Slack

ORCA sends Slack messages using Block Kit. Each notification includes a header block with the alert title and a section block with the event details.

```json theme={null}
{
  "blocks": [
    {
      "type": "header",
      "text": {
        "type": "plain_text",
        "text": "Quality Drop Alert"
      }
    },
    {
      "type": "section",
      "text": {
        "type": "mrkdwn",
        "text": "Quality score for *customers.csv* dropped from 87 to 72."
      }
    }
  ]
}
```

### Microsoft Teams

ORCA sends Teams messages using Adaptive Cards v1.4. Each notification includes a title block and a description block.

```json theme={null}
{
  "type": "message",
  "attachments": [
    {
      "contentType": "application/vnd.microsoft.card.adaptive",
      "content": {
        "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
        "type": "AdaptiveCard",
        "version": "1.4",
        "body": [
          {
            "type": "TextBlock",
            "text": "Quality Drop Alert",
            "weight": "Bolder",
            "size": "Medium"
          },
          {
            "type": "TextBlock",
            "text": "Quality score for customers.csv dropped from 87 to 72.",
            "wrap": true
          }
        ]
      }
    }
  ]
}
```

## Failure handling

ORCA tracks consecutive delivery failures for each webhook. If a webhook URL becomes unreachable or returns errors, the failure count increments. You can monitor this in the webhook list view and re-test the connection after fixing the issue.

## Limits

* Maximum **10 webhooks** per organisation
* Webhook test requests have a **10-second timeout**
* Webhook URLs are stored securely and displayed masked (only the last 8 characters are visible)

## API reference

All webhook management endpoints require admin authentication except listing (any authenticated user). Base path: `/api/v1`.

| Method   | Endpoint                      | Description                   | Auth     |
| -------- | ----------------------------- | ----------------------------- | -------- |
| `GET`    | `/webhooks`                   | List all webhooks for the org | Any user |
| `POST`   | `/webhooks`                   | Create a new webhook          | Admin    |
| `PATCH`  | `/webhooks/{webhook_id}`      | Update a webhook              | Admin    |
| `DELETE` | `/webhooks/{webhook_id}`      | Delete a webhook              | Admin    |
| `POST`   | `/webhooks/{webhook_id}/test` | Send a test message           | Admin    |

### Example: create a Slack webhook

```bash theme={null}
curl -X POST https://api.orca-klavest.app/api/v1/webhooks \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Data team Slack alerts",
    "platform": "slack",
    "webhook_url": "https://hooks.slack.com/services/T00/B00/xxxx",
    "event_types": ["quality_drop", "gdpr_detected", "contract_violation"],
    "enabled": true
  }'
```

### Example: test a webhook

```bash theme={null}
curl -X POST https://api.orca-klavest.app/api/v1/webhooks/{webhook_id}/test \
  -H "Authorization: Bearer $TOKEN"
```

The response indicates whether the test message was delivered:

```json theme={null}
{
  "data": {
    "success": true,
    "error": null
  }
}
```