Sign in
Webhooks

Create webhook

Create a new webhook configuration. Maximum 50 webhooks per user.

name, url and events are required. url must be a valid URL and events must contain at least one event. Whitespace is trimmed from url before validation.

Webhooks are auto-disabled only once the endpoint has had no successful delivery for 3 days AND has either reached 20 consecutive terminal failures (each one an event that exhausted the full retry ladder) or been failing continuously for 3 days. The owner is emailed; re-enable it with isActive: true.

A restricted (zrk_) API key can only subscribe to events whose resource group the key holds; an event outside the key's groups is rejected with 403, so a restricted key can never create a subscription broader than itself.

disabledResourceGroups restricts the subscription itself, independently of which key or session later reads it. Events in a disabled group are dropped before delivery to this endpoint, on live delivery and on every replay path (test fire, redelivery, dead-letter requeue), even if they are listed in events. Omit it to receive everything in events, which is how existing subscriptions behave. A restricted key's own disabled groups are always unioned in.

profileIds pins the subscription to a set of profiles and accountIds to a set of connected accounts: only events attributable to one of the listed ids are delivered, and a subscription with both lists must match on both. Use them to send test accounts to a staging endpoint. Ids outside your team are rejected with 404 (profile_not_found, account_not_found).

post/v1/webhooks/settings

Request body

namestring required

Webhook name (1-50 characters)

urlstring uri required

Webhook endpoint URL (must be a valid URL, whitespace trimmed)

secretstring

Secret key for HMAC-SHA256 signature verification

eventsstring[] required

Events to subscribe to (at least one required)

isActiveboolean

Enable or disable webhook delivery. Defaults to true when omitted.

customHeadersobject

Custom headers to include in webhook requests

disabledResourceGroupsstring[]

Resource groups this subscription does not receive (opt-out denylist). Omit or send an empty array to receive every event in events. Listing a group here drops its events before delivery and on every replay path. Set at creation it applies to everything this subscription ever receives; changed later via PUT it applies to events emitted after the change, with a five-minute tail for events already queued (see that operation). When the caller is a restricted (zrk_) key, that key's own disabled groups are unioned into whatever you send here, so a restricted key can never create a subscription wider than itself.

profileIdsstring[]

Profiles this subscription receives events for. Omit or send an empty array to receive every profile. Every id must be a profile in your team, otherwise the request fails with 404 profile_not_found and nothing is created. Typical use is routing the profile that holds test accounts to a staging endpoint.

accountIdsstring[]

Connected accounts this subscription receives events for. Omit or send an empty array to receive every account. Every id must be an account in your team, otherwise the request fails with 404 account_not_found and nothing is created. Combine with profileIds to narrow further; both must match.

Response

Webhook created successfully

successboolean

Changes