Why This Webhook Exists
All Virifi API operations except document signing return an immediate response.
Document signing is different.
Signing is an asynchronous process involving:
User interaction
External identity verification (PES)
Multiple signers
Time delays outside API control
Because of this, signing status cannot be reliably delivered via API response or email alone. Webhooks provide the only reliable, real-time mechanism to track signing progress and completion.
Scope & Limitations
This webhook is triggered only for document signing workflows initiated via:
POST /sign-document
No other API operation sends webhook events.
If you are looking for certification, verification, or revocation results, those are returned synchronously in the API response and do not use webhooks.
Webhook Setup
The webhook endpoint URL is provided by the client
The endpoint must accept
POSTrequestsPayloads are delivered in JSON
Authentication uses the same Developer API Key as all other Virifi APIs
Authentication
Webhook requests include the standard Authorization header:
{ "Content-Type": "application/json", "Authorization": "Bearer API-KEY" }Requests without a valid API key should be rejected.
Signing Events
Only the following signing-related events are sent:
Event | Description |
| Signing process successfully created |
| All required signatures completed |
| Signing rejected, expired, or failed |
| Signing cancelled by initiator |
Do not assume event ordering. Always treat events as state updates, not commands.
Webhook Payload Example
{ "event": "sign.completed",
"type": "sign_by_yourself",
"timestamp": "2026-0-000",
"data": { "documentId": "6983750d8a13ead08211f410",
"documentHash": "3f55b1dbd5a8acdb181fc******************de6ba63c1b928b21315b", "organizationId": "66571c********742301",
"signatureType": "AES",
"status": "completed",
"signerEmail": "[email protected]" } }Payload Fields
Field | Description |
| Signing event type |
| Event creation time (ISO-8601) |
| Virifi document ID |
| Blockchain document hash |
| Owning organization |
|
|
| Current signing state |
Expected Webhook Response
Your endpoint must return:
HTTP 2xx → Event accepted
Any other response → Delivery considered failed
Webhook delivery is best-effort. Events are not guaranteed to be retried.