# Webhook API

{% if !(visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard') %}
{% hint style="info" %}
Webhook integrations are available to organizations with a Soda license. [Contact us](mailto:support@soda.io) to learn more.
{% endhint %}

Soda Cloud can push real-time events to any endpoint you control, so the moment a check fails, an incident moves, or a contract is published, the systems your team already lives in find out about it. Webhooks turn Soda Cloud into a source of **structured**, **timely** **signal** for the rest of your operational stack. Common patterns include:

* **Pipe alerts into your on-call rotation**, so failed checks open pages or tickets in PagerDuty, Opsgenie, or whatever tool your team is on.
* **Drive automation:** kick off remediation jobs, pause downstream pipelines, or trigger reruns when specific checks fail.
* **Sync data quality events into your own observability stack**, alongside your existing logs and metrics.
* **Keep external systems of record in lockstep** with Soda incidents and contract changes, so your catalog, ticketing tool, or governance platform reflects the latest state.
  {% endif %}

***

{% if visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard' %}

## Setup

To create a Webhook integration, you must have **Organization Settings** permissions.

#### Add Integration

{% stepper %}
{% step %}
Go to **Organization Settings > Integrations**
{% endstep %}

{% step %}
Click **Add Integration**
{% endstep %}

{% step %}
Choose **Webhook** as the integration type

<figure><img src="/files/dFhIIjTlUOThxpgjOSMQ" alt=""><figcaption></figcaption></figure>
{% endstep %}
{% endstepper %}

### Configure Webhook

Provide the required fields:

* **Name** – The name of your integration
* **Webhook URL** – The endpoint to send the events to
* **Secret (optional)** – Used to sign the payload

<figure><img src="/files/VElJ4PEJLroErvSd2PoB" alt="" width="362"><figcaption></figcaption></figure>

### Event Testing

After creation, you can simulate payloads for development and testing.

This allows you to preview example payloads for each event type using random values.

<figure><img src="/files/tud6fu1ND1ZZYrb20AMF" alt="" width="361"><figcaption></figcaption></figure>
{% endif %}

### Scopes

Webhooks can be configured to listen for one or more **event scopes**:

| Scope                   | Description                                                                 |
| ----------------------- | --------------------------------------------------------------------------- |
| **Alert Notifications** | Triggered when a check result causes an alert (based on notification rules) |
| **Incidents**           | Triggered when incidents are created or updated in Soda Cloud               |
| **Contracts**           | Triggered when a data contract is published (created or updated)            |

{% if visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard' %}
Alert Notifications require active **notification rules**. Learn more about [Broken mention](broken://pages/GAK0Cdoq2hZmucVmrovV)

<figure><img src="/files/L8WCgEAFaD0yozigIyfS" alt="" width="363"><figcaption></figcaption></figure>
{% endif %}

***

{% if !(visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard') %}

## Event Types

{% endif %}

{% if visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard' %}

## Event Types and Payloads

{% endif %}

Depending on the selected scope, one or more of the following event types will be sent to your endpoint:

### Check Evaluation

Sent when a check evaluation triggers an alert. It carries the check's outcome and a link back to the result in Soda Cloud so a human can investigate further.

{% if visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard' %}
Scope: `alert_notification`\
Triggered when a check result triggers an alert.

Alert Notifications require active **notification rules to use the webhook as a recipient**.

**Payload structure:**

```bash
{
  "event": "checkEvaluation",
  "checkResults": [CheckResult, ...]
}
```

#### CheckResult

| Field                      | Type    | Description                                                                                            |
| -------------------------- | ------- | ------------------------------------------------------------------------------------------------------ |
| `id`                       | string  | Unique ID of the check result                                                                          |
| `sodaCloudUrl`             | string  | Link to the check result in Soda Cloud                                                                 |
| `definition`               | string  | YAML check definition                                                                                  |
| `datasets`                 | array   | List of associated datasets (see [#datasets](#datasets "mention") object)                              |
| `column`                   | string  | List of associated datasets (see [#attributes](#attributes "mention") object)                          |
| `attributes`               | array   | List of associated datasets (see `Dataset` object)                                                     |
| `value`                    | numeric | The field shows the actual value calculated for the check (the result used to determine pass or fail). |
| `evaluationStatus`         | string  | `pass`, `fail`, or `notEvaluated` `excluded`                                                           |
| `outcome` (deprecated)     | string  | Deprecated, replaced by `evaluationStatus`.                                                            |
| `dataTimestamp`            | string  | ISO 8601 timestamp of data                                                                             |
| `diagnostics` (deprecated) | object  | Deprecated, replaced by `value`.                                                                       |
| `agreement`(deprecated)    | object  | Deprecated, V3 concept.                                                                                |
| `name`                     | string  | Name of the check                                                                                      |

#### Datasets

| Field        | Type   | Description                                                                  |
| ------------ | ------ | ---------------------------------------------------------------------------- |
| id           | string | Unique ID of the dataset                                                     |
| sodaCloudUrl | string | Link to the dataset in Soda Cloud                                            |
| name         | string | Dataset name (technical name)                                                |
| label        | string | Display label for the dataset                                                |
| tags         | array  | List of dataset tags                                                         |
| owners       | array  | List of dataset owners (see [#owner](#owner "mention")object)                |
| datasource   | object | Datasource information (see [#datasource](#datasource "mention")object)      |
| attributes   | array  | List of dataset attributes (see [#attributes](#attributes "mention") object) |

#### Owner

| Field | Type   | Description                     |
| ----- | ------ | ------------------------------- |
| type  | string | Owner type (for example `user`) |
| id    | string | Unique ID of the owner          |
| email | string | Owner email address             |

#### Datasource

| Field | Type   | Description                      |
| ----- | ------ | -------------------------------- |
| id    | string | Unique ID of the datasource      |
| name  | string | Datasource name (technical name) |
| label | string | Display label for the datasource |

#### Attributes

| Field       | Type   | Description                     |
| ----------- | ------ | ------------------------------- |
| id          | string | Unique ID of the attribute      |
| name        | string | Attribute name (technical key)  |
| label       | string | Display label for the attribute |
| value       | string | Attribute value                 |
| {% endif %} |        |                                 |

***

### **Incident Created**

**S**ent when a new incident is opened, with enough context for a downstream system to create a corresponding ticket, channel, or page.

{% if visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard' %}
Scope: `incidents`\
Triggered when a new incident is reported

```bash
{
  "event": "incidentCreated",
  "incident": Incident
}
```

#### Incident

| Field                     | Type   | Description                                                                              |
| ------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| `id`                      | string | Incident ID                                                                              |
| `sodaCloudUrl`            | string | URL to view the incident                                                                 |
| `number`                  | number | Human-readable incident number                                                           |
| `title`                   | string | Incident title                                                                           |
| `description`             | string | Incident description                                                                     |
| `severity`                | string | `low`, `medium`, `high`, `critical`                                                      |
| `status`                  | string | `reported`, `in_progress`, `resolved`, etc.                                              |
| `created`                 | string | ISO timestamp                                                                            |
| `lastUpdated`             | string | ISO timestamp                                                                            |
| `reporter`                | object | User who reported the incident (see [#reporter](#reporter "mention") object)             |
| `checkResults`            | array  | List of related `CheckResult` objects (see [#checkresult](#checkresult "mention")object) |
| `incidentLinkCallbackUrl` | string | Link to update or interact with the incident (optional)                                  |

#### **Reporter**

| Field | Type   | Description               |
| ----- | ------ | ------------------------- |
| id    | string | Unique ID of the reporter |
| email | string | Reporter email address    |

#### **IncidentLinkCallBackUrl**

This property allows you to add links to incidents that can point to external integrations. To add a link, do a POST call with the following body:

```bash
{
  "url": string,
  "text": string
}
```

{% endif %}

***

### Incident Updated

Sent when an existing incident changes, so downstream systems can stay in sync as severity, status, or scope evolves.

{% if visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard' %}
Same structure as `incidentCreated`, but triggered when an incident is updated.

```bash
{
  "event": "incidentUpdated",
  "incident": Incident
}
```

### Incident

| Field | Type  | Description                                                                                                                                      |
| ----- | ----- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
| ...   | ...   | Uses the same structure as the Incident created event. See [#incident](#incident "mention")                                                      |
| links | array | Links to integration resources set using [#incidentlinkcallbackurl](#incidentlinkcallbackurl "mention") (see [#links](#links "mention") object). |

#### Links

| Field           | Type   | Description                               |
| --------------- | ------ | ----------------------------------------- |
| integrationType | string | Integration type (for example `slack`)    |
| url             | string | Link to the external integration resource |
| {% endif %}     |        |                                           |

***

### Contract Published

Sent when a data contract is published or updated, useful for catalog sync, change auditing, or kicking off downstream validation.

{% if visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard' %}
Scope: `contracts`\
Triggered when a contract is published or updated.

```bash

{
  "event": "contractPublished",
  "contract": Contract
}
```

#### `Contract` **object**

| Field          | Type      | Description                                                   |
| -------------- | --------- | ------------------------------------------------------------- |
| `dataset`      | string    | Fully qualified name of the dataset the contract applies to   |
| `prefixes`     | string\[] | *(Deprecated)* – Use `dataset` instead to identify the target |
| `datasource`   | string    | Name of the data source                                       |
| `author`       | object    | Information about the user who published the contract         |
| `author.id`    | string    | Soda Cloud user ID                                            |
| `author.email` | string    | Email of the user who published the contract                  |
| `contents`     | string    | The full YAML content of the contract as a string             |
| {% endif %}    |           |                                                               |

<br>

***

{% if (visitor.claims.plan === 'datasetStandard')
%}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Dataset Standard license** documentation. Learn more about [Documentation access & licensing](/reference/documentation-access-and-licensing.md).
{% endhint %}
{% endif %}

{% if (visitor.claims.plan === 'enterprise')
%}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Team license** documentation. Learn more about [Documentation access & licensing](/reference/documentation-access-and-licensing.md).
{% endhint %}
{% endif %}

{% if (visitor.claims.plan === 'enterpriseUserBased')
%}
{% hint style="success" %}
You are **logged in to Soda** and seeing the **Enterprise license** documentation. Learn more about [Documentation access & licensing](/reference/documentation-access-and-licensing.md).
{% endhint %}
{% endif %}

{% if !(visitor.claims.plan === 'enterprise' || visitor.claims.plan === 'enterpriseUserBased' || visitor.claims.plan === 'datasetStandard')
%}
{% hint style="info" %}
You are **not logged in to Soda** and are viewing the default public documentation. Learn more about [Documentation access & licensing](/reference/documentation-access-and-licensing.md).
{% endhint %}
{% endif %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.soda.io/reference/webhook-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.