API ReferenceWebhooks

Create webhook endpoint

Creates a new webhook endpoint for the authenticated organization. The signing secret is returned only in this response — store it securely.

Authentication

X-API-Keystring

Organization API key. Keys are prefixed with vk_live_ (production) or vk_sandbox_ (sandbox).

Headers

Verifa-VersiondateOptional

API version date string (e.g. 2026-02-01). If omitted, the version pinned to your API key is used.

Request

This endpoint expects an object.
urlstringRequiredformat: "uri"
The HTTPS URL to receive webhook events.
labelstringOptional

Human-readable label for this endpoint.

descriptionstringOptional
enabled_eventslist of stringsOptional
Event types to subscribe to. Omit or pass `["*"]` to receive all events. Available types include `session.approved`, `session.declined`, `session.resubmission-required`, `identity.created`, `identity.updated`, `identity.archived`, `identity.restored`, `identity.tag-added`, `identity.tag-removed`.
attribute_blocklistlist of stringsOptional
Attribute paths to exclude from webhook payloads.
event_filter_conditionsmap from strings to anyOptional
Conditional filters applied before dispatching events to this endpoint.
api_versionstring or nullOptional
key_inflectionenumOptional
Allowed values:

Response

Webhook endpoint created. The secret field is only returned here.

created_atdatetime
enabledboolean
enabled_eventslist of strings
Event types this endpoint is subscribed to. Empty means all events.
environmentenum
Allowed values:
idstring
secretstring

HMAC signing secret for verifying webhook payloads. Only returned at creation and secret rotation — store it securely.

updated_atdatetime
urlstringformat: "uri"
api_versionstring or null
attribute_blocklistlist of strings
Attribute paths to exclude from webhook payloads.
descriptionstring or null
event_filter_conditionsmap from strings to any
Conditional filters applied before dispatching events to this endpoint.
key_inflectionenum
Allowed values:
labelstring or null

Errors

401
Unauthorized Error
422
Unprocessable Entity Error