Verification webhooks (API)

Your system is informed about changes in verification status via verification webhooks. These are different from document webhooks — they have their own events and, in addition, they sign messages (HMAC) so that you can verify they really came from Signi.

Events

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

Subscribing

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

"webhooks": [
    { "event": "verification.approved", "url": "https://vase-aplikace.cz/overeni-schvaleno" },
    { "event": "verification.rejected", "url": "https://vase-aplikace.cz/overeni-zamitnuto" }
]

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

In the response, a secret is returned for each subscription — the key for verifying the message signature:

"webhooks": [
    { "event": "verification.approved", "url": "https://vase-aplikace.cz/overeni-schvaleno", "secret": "…" }
]

Caution: the secret is returned only once, right here. Save it immediately — you will not get it from the API again.

Default workspace 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 go next

• Signi verification — how it works