Skip to navigation
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
Allowed values:
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 nullOptional
attribute_blocklistlist of stringsOptional
Attribute paths to exclude from webhook payloads.
descriptionstring or nullOptional
event_filter_conditionsmap from strings to anyOptional
Conditional filters applied before dispatching events to this endpoint.
key_inflectionenumOptional
Allowed values:
labelstring or nullOptional

Errors

401
Unauthorized Error
422
Unprocessable Entity Error