Webhooks for Anomaly Detection and Check Results¶

Alation Cloud Service Applies to Alation Cloud Service instances of Alation

Alation Data Quality supports outbound webhooks that deliver real-time notifications when Data Quality checks or Anomaly Detection jobs change state. Webhooks allow you to integrate data quality and anomaly events into any system of your choice, including PagerDuty, Jira, Slack, custom incident platforms, or internal data pipelines.

Supported Webhook Events¶

Webhooks are emitted for specific job types and their lifecycle states. You can receive events at the monitor level, which summarizes the entire job run, or at the individual check level for more granular control.

Monitor-level Events¶

Event type	Job type	Description
`dq.run.completed`	Data Quality	A DQ job completed successfully.
`dq.run.failed`	Data Quality	A DQ job completed but one or more checks failed.
`dq.run.errored`	Data Quality	A DQ job encountered a system or runtime error.
`anomaly.run.completed`	Anomaly Detection	An anomaly detection run completed successfully.
`anomaly.run.failed`	Anomaly Detection	An anomaly detection run detected one or more anomalies.
`anomaly.run.errored`	Anomaly Detection	An anomaly detection run encountered a system or error.

Check-level Events¶

Event type	Job type	Description
`dq.check.passed`	Data Quality	An individual DQ check passed.
`dq.check.failed`	Data Quality	An individual DQ check failed.
`dq.check.errored`	Data Quality	An individual DQ check encountered an error.
`anomaly.check.normal`	Anomaly Detection	An anomaly metric was within its expected range.
`anomaly.check.detected`	Anomaly Detection	An anomaly was detected for a metric.
`anomaly.check.errored`	Anomaly Detection	An anomaly check encountered an error.

Delivery Guarantees¶

Alation Data Quality provides the following delivery guarantees for webhook events:

At-least-once delivery: The system may retry sending an event if it fails to receive a success confirmation from your endpoint.
Stable event ID: Each event includes a unique event_id. Your receiving system must use this ID to deduplicate events and correctly handle retried deliveries.

Webhook Endpoint Requirements¶

To successfully receive webhook payloads, your webhook endpoint must meet the following requirements:

Return a 2xx HTTP response to acknowledge successful receipt.
Respond within the configured timeout window.
Handle retried deliveries by deduplicating requests using the event_id.

HTTP Request Format¶

Alation Data Quality sends webhook requests using the POST method with a Content-Type of application/json.

The request includes the following headers:

Header	Description
`X-Webhook-EventId`	A unique identifier for the event.
`X-Webhook-Event-Type`	The name of the event, such as dq.run.failed.
`X-Webhook-DeliveryId`	A unique ID for each delivery attempt. This value changes if the event is retried.
`X-Tenant-Id`	Your Alation Tenant ID.
`X-Webhook-Timestamp`	The timestamp when the event was sent.

Example Payload: dq.run.failed

{
    "schema_version": "1.0",
    "event_id": "event_262_42",
    "event_type": "dq.run.failed",
    "occurred_at": "2026-03-06T10:42:31Z",
    "tenant_id": "fbcf89fe-3fbf-4b05-86e0-90f4762b717b",
    "job_type": "data-quality",
    "run": {
        "run_id": "run_42",
        "status": "FAILED"
},
"dq": {
    "summary": {
        "total_checks": 120,
        "passed": 110,
        "failed": 8,
        "errored": 2
    },
    "failed_by_table": [
        {
            "table_rank": 1,
                "table": {
                    "fqn": "prod.sales.orders",
                    "steward": [
                        {
                            "otype": "user",
                            "id": 2,
                            "name": "Data Steward",
                            "email": "data.steward@company.com"
                        }
                    ],
                    "tags": ["finance", "gold"],
                    "row_count": 1500
                },
                "failed_checks": [
                    {
                        "check_rank": 1,
                        "check_id": "6fa983b5-96b6-4136-8678-0fb7d8ebcb9c",
                        "check_type": "freshness",
                        "status": "FAIL",
                        "message": "Table should be updated within 24 hours",
                        "object_name": "orders",
                        "observed_value": "36.4"
                    }
                ]
            }
        ]
    },
    "job": {
        "job_id": "42",
        "monitor_name": "Daily Sales DQ",
        "monitor_id": "262"
    },
    "job_context": {
        "template_variables": {
            "MIN_TS": "2026-03-01",
            "REGION": "us-west-2"
            }
        }
}

Authenticate Incoming Webhooks¶

Each webhook subscription uses one authentication method. You can choose from two options:

Static Header Token: Include a static token with every webhook request. Alation sends either X-Webhook-Token: <your-token> or Authorization: Bearer <your-token>.
OAuth2 Client Credentials: For more secure authentication, provide an OAuth token URL, Client ID, Client secret, and optional scopes. Alation fetches and caches access tokens automatically and calls your endpoint using Authorization: Bearer <access_token>.

Payload Structure and Metadata¶

All events share a common top-level envelope structure. Events for failed and completed jobs are automatically enriched with metadata from your Alation catalog, which enables smarter routing and incident creation.

Enriched metadata includes:

Table metadata: Stewards and Tags
Column metadata: Stewards and Tags

This enrichment allows you to build powerful automations, such as auto-routing incidents to the correct steward, filtering alerts by tags, or escalating issues on critical data assets.

Schema Versioning¶

All webhook payloads include a schema_version field. Additive changes, such as new fields, are backward-compatible and do not increment the version. Any breaking changes will be versioned and communicated in advance.