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

Only users with the Manage Organization Settings global role can define webhook integrations. Global and Dataset Roles

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.

1. Select the integration type: Webhook, and click next.

1. 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.

1. 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 ✅

1. 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.

1. 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 <token> on each request. The token request itself is form-urlencoded and always carries grant_type=client_credentials.

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.

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.

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.

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

---

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

If you do have a Soda license, make sure to log in to Soda Cloud in this same browser.