> For the complete documentation index, see [llms.txt](https://docs.soda.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.soda.io/integrations/webhook.md). # Webhook The **Webhook Integration** in Soda Cloud allows you to send notifications about **check results** (based on notification rules) and **incident updates** to external systems, such as monitoring tools, incident management platforms, or custom endpoints. This integration is ideal for teams who want to build custom workflows or integrate Soda Cloud alerts into their existing tools. ### Set Up a Webhook Integration {% hint style="warning" %} Only users with the **Manage Organization Settings** global role can define webhook integrations. [Global and Dataset Roles](/organization-and-admin-settings/global-and-dataset-roles.md) {% endhint %} Follow these steps to configure a Webhook integration in Soda Cloud: 1. Go to the **Integrations** section in **Settings**. 2. Click the **+** button to add a new integration.

3. Select the integration type: **Webhook,** and click next.

4. Configure the Webhook * **Name**: Provide a clear name for your integration. * **URL**: Enter the Webhook endpoint where Soda Cloud should send notifications. **Headers**: (Optional) * Add authentication or custom headers required by your endpoint. * **Authentication**: (Optional) Instead of, or in addition to, static headers, authenticate the requests with OAuth 2.0 client credentials, described in the section below.

5. Test the Webhook * Use the built-in testing tool to simulate events and validate your Webhook integration. * You can select different event types to test and develop your integration. * For the exact payload structure and details, see the [Webhook reference ✅](https://slite.com/api/public/notes/5e-Y6TfFiYmlii/redirect)

6. Choose the events to send * **Alert Notifications**: The integration becomes **available for use in notification rules**. It will only send notifications when you explicitly configure a notification rule to use this Webhook. * **Incidents**: Triggered when users create or update incidents in Soda Cloud. * **Contracts**: Triggered when users publish new or updated contracts in Soda Cloud.

6. Click Save to apply ### Authenticate requests with OAuth 2.0 Instead of, or in addition to, static headers, Soda Cloud can obtain an access token from your provider and send it with every webhook request. When you enable **Authenticate requests with OAuth 2.0 client credentials**, Soda Cloud acts as the OAuth client: it requests a token from your provider's token endpoint using the `client_credentials` grant, then attaches it as `Authorization: Bearer ` on each request. The token request itself is form-urlencoded and always carries `grant_type=client_credentials`. {% hint style="info" %} You do not set an `Authorization` header yourself. Any `Authorization` header you put in **Headers** is stripped and replaced with the token. Your other static headers are still sent. {% endhint %}

Field	Required	Description
Token URL	yes	The token endpoint of your provider, over `https://`. Must be publicly resolvable.
Client ID	yes	The client identifier your provider issued for Soda Cloud.
Client Secret	yes	Write-only: never returned on read. When you edit the integration, leave it blank to keep the stored value, or enter a new value to replace it.
Scope	no	The scope to request, if your provider expects one. Some providers restrict access per client application instead, in which case leave it blank.
Additional token request parameters	no	Name/value rows merged into the body of the token request. See below.

#### Additional token request parameters Some providers expect parameters on the token request beyond the fields above, such as an audience or resource identifier, or a gateway-specific value. Add them as name/value rows and Soda Cloud merges them into the token request body. Consult your provider's documentation for which parameters it expects. The names `grant_type`, `client_id`, `client_secret`, and `scope` are reserved in any capitalisation, because Soda Cloud sets them from the fields above. A name can appear only once. {% hint style="warning" %} These values are **not** treated as secrets: they are returned by the API and visible to anyone who can view the integration. Put credentials in the **Client Secret** field, which is write-only. {% endhint %} #### How Soda Cloud handles the token * The access token is cached per integration and reused across events, rather than requested per event. * It is refreshed 60 seconds before it expires. If the provider returns no `expires_in`, Soda Cloud assumes 5 minutes. * If a webhook request comes back `401 Unauthorized`, Soda Cloud discards the cached token, fetches a new one, and retries the request once. * A token request that does not complete within 10 seconds times out, and the webhook request fails. * Changing the token URL, client ID, or client secret discards the cached token, so the next event fetches a new one. ### Use in Notification Rules After configuring your Webhook integration with the Alert Notification scope, you can use it in your **notification rules** to send alerts when specific checks fail. When creating or editing a notification rule, select your configured **Webhook** integration as the recipient. > For detailed steps and advanced examples, see the [Notifications](/manage-issues/notifications.md) *** {% hint style="info" %} You are **not logged in to Soda** and are viewing the default public documentation. Learn more about [Licensing & documentation access](/reference/documentation-access-and-licensing.md). If you do have a Soda license, make sure to **log in to Soda Cloud in this same browser**. {% endhint %} --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## 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, and the optional `goal` query parameter: ``` GET https://docs.soda.io/integrations/webhook.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. 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.