API ReferenceWebhooks

Create webhook endpoint

Creates a new webhook endpoint for the authenticated organization. The `secret` field in the response is the **per-endpoint** signing secret (`whsec_*`) used to verify `X-Verifa-Signature` HMAC headers on deliveries to this URL. Each endpoint has its own independent secret — this is **not** the legacy organization-level webhook secret. It is returned only in this response (and on `POST /webhooks/endpoints/{endpoint_id}/rotate-secret`); Verifa does not store the plaintext, so capture and 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
idstring
secretstring

Per-endpoint HMAC-SHA256 signing secret. Used to verify the X-Verifa-Signature header on outbound webhook deliveries (HMAC over f"{t}.{raw_body}"). Always begins with whsec_. Only returned at endpoint creation and secret rotation — Verifa does not store the plaintext secret after this response, so capture and 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
labelstring or null

Errors

401
Unauthorized Error
422
Unprocessable Entity Error