Create a webhook

POST/v1/campaigns/{campaign_id}/webhooks

Scope: campaigns:write

Registers an HTTPS URL to receive this campaign's prospect_response events. Answers 201 when a webhook is created, 200 when a disabled webhook for the same URL is enabled again, and 409 DUPLICATE_WEBHOOK when that URL is already active.

A campaign has one response webhook. When a different URL already holds it, the request answers 409 WEBHOOK_SLOT_TAKEN unless you send replace: true, which repoints that webhook at the new URL (200, with replaced: true); the previous receiver then stops getting this campaign's events.

Send your own secret so both sides hold the same signing key, or leave it out and one is generated for you.

A generated secret appears in this response and nowhere else. Store it before you discard the response; if you lose it, set a new one.

Headers

AuthorizationstringRequired
Bearer followed by a space and your API key, for example Bearer vk_….

Path parameters

campaign_idstring · uuidRequired
ID of the campaign.

Request body

webhook_urlstringRequired
URL to receive webhook events
at most 2,000 charactersExample "https://api.example.com/webhooks/victoria"
replaceboolean
A campaign has one response webhook. When a different URL already holds it, the request is refused with WEBHOOK_SLOT_TAKEN unless this is true, in which case that webhook is repointed at webhook_url and the previous receiver stops getting this campaign's responses.
Default false
secretstring or null
Caller-supplied HMAC signing secret so the receiver holds the same key; generated server-side when omitted (and then unrecoverable by the receiver)
at least 16 charactersat most 2,000 characters

Response

200 / 201

webhook_idstringRequired
ID of the webhook record
createdboolean or null
True when a new webhook was created, false when an existing disabled one was re-enabled
messagestring
Default "Webhook activated successfully"
replacedboolean or null
True when an existing webhook for a different URL was repointed (replace=true)
secretstring or null
Present only when the signing secret was generated server-side, and only in this response: store it now, it cannot be retrieved again. Absent when you supplied your own.
successboolean
Default true

Errors

Errors share one JSON body: success, error, message, optional details, and request_id.

Status	Code	Meaning
400	VALIDATION_ERROR	The request didn't match the endpoint's schema: a missing or malformed field, a bad query parameter, or a value out of range. `details.errors` lists each failing field with its `field`, `message` and `type`.
400	INVALID_WEBHOOK_URL	The webhook URL must use `https` and resolve to a public address.
401	UNAUTHORIZED	The `Authorization` header is missing or malformed, or the API key is unknown or has been deactivated.
401	API_KEY_EXPIRED	The API key is past its expiry date. Create a new key in the Victoria AI app.
403	INSUFFICIENT_SCOPE	The API key doesn't have the scope this endpoint requires, such as `leads:write`.
403	ORGANIZATION_DEACTIVATED	The organization that owns this API key has been deactivated.
404	CAMPAIGN_NOT_FOUND	No campaign with this ID exists in your organization.
404	NOT_FOUND	No endpoint matches the path. A resource ID in the path that isn't a valid UUID also answers `NOT_FOUND`.
409	DUPLICATE_WEBHOOK	An active webhook for this URL already exists on the campaign. `details.webhook_id` identifies it.
409	WEBHOOK_SLOT_TAKEN	A campaign has one response webhook, and a different URL already holds this campaign's. `details.webhook_id` identifies it. Send `replace: true` to repoint that webhook at the new URL; the previous receiver then stops getting this campaign's events.
413	PAYLOAD_TOO_LARGE	The request body is larger than 1 MB.
429	RATE_LIMITED	Too many requests for this API key: more than 100 a minute to one endpoint, or 600 a minute in total. Retry after the number of seconds in the `Retry-After` header. See Rate limits.
500	INTERNAL_ERROR	Something failed on our side. The response never includes internal details; quote its `request_id` when you contact support.
503	UPSTREAM_TIMEOUT	A service the API depends on timed out. The request is safe to retry.
503	AUTH_UNAVAILABLE	The API key couldn't be checked because the authentication service was unavailable. The request is safe to retry.

Response headers

Header	Description
`X-Request-ID`	Correlation ID for the request, also returned as `request_id` in error bodies. Send your own `X-Request-ID`, up to 128 letters, digits, `.`, `_`, `:` or `-`, and it's used instead.
`RateLimit-Limit`	Requests allowed to this endpoint per minute.
`RateLimit-Remaining`	Requests you can still send to this endpoint right now.
`RateLimit-Reset`	Seconds until the endpoint's full limit is available again.
`Retry-After`	On a `429`: seconds to wait before retrying.