Skip to navigation

Webhook configs

A reusable, signed webhook target shared by campaigns and deployments.
View as Markdown

A webhook config stores a webhook target once and lets campaigns and deployments reference it by ID. Every delivery made through a webhook config is signed, so your server can prove each request came from Sarvam.

Why a stored config

Without a webhook config you set a raw URL on each campaign or deployment. That works, but every delivery is unsigned — your server takes the request on trust.

With a webhook config:

  • Deliveries are signed. Each request carries an HMAC-SHA256 signature your server verifies against the config’s signing secret — see Campaign webhook payload and Deployment webhook payload.
  • Change the URL in one place. Campaigns and deployments referencing the config by ID immediately deliver to the updated URL — no campaign or deployment edits needed.
  • Custom headers. Set up to 10 custom headers (for example an auth header for your endpoint) sent with every delivery.

The signing secret

When you create a webhook config, the response includes a signing_secret. This is the only time the secret is ever returned — list, get, and update responses never include it. Store it securely when you create the config.

If you lose the secret, create a new webhook config and update the campaigns and deployments to reference it, then delete the old one.

Limits

  • A workspace can hold at most 5 webhook configs. Creating a sixth returns HTTP 429.
  • The name is 1-50 characters (letters, digits, spaces, underscores, hyphens).
  • The URL must be HTTPS.
  • A webhook config referenced by a non-terminal campaign or deployment cannot be deleted — the delete request returns HTTP 409 and the error message lists the referencing campaign and deployment IDs.

Using a config

Reference the config from a campaign or deployment by setting webhook_config to {"webhook_id": "...", "metadata": {...}} instead of {"url": "..."}. Exactly one of url and webhook_id may be set. An unknown webhook_id is rejected with HTTP 404.

{
"webhook_config": {
"webhook_id": "019ec7f2-8d34-7c1a-9f22-3b9d4e5a6c11",
"metadata": { "team": "collections" }
}
}