Verification webhooks

ℹ️ The new version of Signi verification (including this API) will be published to production during September 2026. Until then, the calls are not available and the description may change slightly.

Your system learns about changes in verification status through verification webhooks. These are different from document webhooks — they have their own events and additionally sign the messages (HMAC) so you can verify they really came from Signi.

Events

verification.started, verification.completed (checks finished, awaiting approval), verification.approved, verification.rejected, verification.declined, verification.expired, verification.abandoned.

Subscribing

Webhooks are specified when creating a verification or attaching it to a document, using the webhooks field:

"webhooks": [
    { "event": "verification.approved", "url": "https://your-application.com/verification-approved" },
    { "event": "verification.rejected", "url": "https://your-application.com/verification-rejected" }
]

• The address must be HTTPS and publicly reachable.
• At most one subscription per event; the call will reject keys other than event and url.

The response returns a secret for each subscription — the key used to verify message signatures:

"webhooks": [
    { "event": "verification.approved", "url": "https://your-application.com/verification-approved", "secret": "…" }
]

Warning: the secret is returned only once, right here. Save it immediately — you won't be able to retrieve it from the API again.

Workspace default webhooks

A workspace can have default subscriptions configured. Behavior of the webhooks field:

• omit it — the workspace's default subscriptions are copied to the verification (they use the workspace's long-term shared key, which is not returned in the response — the response is empty),
• send [] — no subscriptions, not even the defaults,
• send your own list — exactly these subscriptions are registered with fresh keys in the response.

For a recycled verification (reused: true), no new subscriptions are registered.

Where to next

• Signi verification — how it works