Webhook API

Webhook integrations allow your system to receive real-time notifications from Soda Cloud when certain events occur, such as check evaluations, incident changes, or contract updates.

---

Setup

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

Add Integration

1. Go to Organization Settings > Integrations

2. Click Add Integration

3. Choose Webhook as the integration type

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

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.

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)

Alert Notifications require active notification rules. Learn more about Notifications

---

Event Types and Payloads

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

---

Check Evaluation

Scope: alert_notification Triggered when a check result triggers an alert.

Alert Notifications require active notification rules to use the webhook as a recipient. See Notification Configuration →

Payload structure:

{
  "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 object)
column	string	List of associated datasets (see Attributes 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 object)
datasource	object	Datasource information (see Datasource object)
attributes	array	List of dataset attributes (see Attributes 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

---

Incident Created

Scope: incidents Triggered when a new incident is reported

{
  "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 object)
checkResults	array	List of related CheckResult objects (see CheckResult 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:

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

Incident Updated

Same structure as incidentCreated, but triggered when an incident is updated.

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

Incident

Field	Type	Description
...	...	Uses the same structure as the Incident created event. See Incident
links	array	Links to integration resources set using IncidentLinkCallBackUrl (see Links object).

Links

Field	Type	Description
integrationType	string	Integration type (for example slack)
url	string	Link to the external integration resource

Contract Published

Scope: contracts Triggered when a contract is published or updated.

{
  "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

---

You are not logged in to Soda and are viewing the default public documentation. Learn more about Documentation access & licensing.