Webhooks

1. Webhook Configuration
To properly receive incoming webhooks, your server should provide an endpoint supporting:
POST requests are either raw in text/plain if encrypted or application/json if no secret wat set 
You can use a service like e.g. https://webhook.site/ to test receiving webhooks from your  developer dashboard.
2. Event Types
Our webhook service supports two events, which describe the status of an Identity. Those are: 
verification.completed: Identity Verification either has completed its processing successfully or has been terminated as failed.
onboarding.completed: Onboarding either has been completed successfully or has been interrupted and set on an awaiting state.
​
Verification Completed
The verification.completed event is triggered when an Identity Verification has completed its processing successfully or has been terminated as failed. The value of the status property can either be VERIFIED if the verification completes successfully or, FAILED if any subprocess has been rejected.
{
  "ticket": "f1662a17-87dc-4ce1-b151-0791d7ed8895",
  "created": 1641600622454,
  "processed": 1641600624552,
  "event": "verification.completed",
  "status": "VERIFIED"
}
Possible statuses
VERIFIED, this is the status when an Identity Verification passed all its subprocesses successfully.
FAILED, this is the status when an Identity Verification  failed to pass any of its subprocesses, eg. liveness detection process.
​
Onboarding Completed
The onboarding.completed event is triggered when an Onboarding has completed its processing successfully or has been interrupted and set on an awaiting state. The value of the status property can either be SUCCESSFUL if the onboarding completes successfully or one of the uploading images has been rejected but Onboarding passed or, AWAITING if any exception has been raised on Onboarding subprocess.
{
  "ticket": "01354631-8b4b-4313-a8d4-2c94ad37949b",
  "created": 1641595132747,
  "processed": 1641595134895,
  "event": "onboarding.completed",
  "status": "SUCCESSFUL"
}
Possible statuses
SUCCESSFUL, this is the status when an Onboarding passed successfully or any uploading images has been rejected but Onboarding itself is correct.
AWAITING, this is the status when an Onboarding failed to pass. Intead of setting it as a failed Onboarding, it awaits for its correction, so this subprocess can be retried as many times as long as it's on this status.
​
Here you find a further description of the response values below, it represents both event responses as these share the same response structure:
Key
Data type
Description
ticket
string
The UUID of the Identity Verification which triggered this webhook. This will help you query our backend API for the details of the Identity Verification.
event
string
The type of event that triggered this webhook.
status
string
This holds the result of the Identity Verification whether it's been processed without any exception or it's been interrupted because of some failure. 

Depending on its verification type, as noted above, its value may be one of these 4 posibilities:
- VERIFIED
- FAILED
- SUCCESSFUL
- AWAITING
created
number
UNIX timestamp, when the Identity Verification was created.
processed
number
UNIX timestamp, when the Identity Verification was processed.
​
3. Security / Encryption
Webhooks are a crucial node to ensure the functionality of your integration, as such, they can be the target of a malicious user aiming to disrupt the service. In order to protect your application from these threats, you must include a 32 bytes-long secret in your webhook configuration, which will be used to encrypt the request body.
When you enable Encryption, the Webhook event is sent as text/plain. Below you'll find an example of how to decipher an incoming webhook request. We assume both variables response_headers and response_body are present in the response you received via the webhook. The cipher initialization vector will be sent over as a 16 bytes metadata (header) of the response.
Javascript
const crypto = require("crypto")
​
// Your response headers from the webhook. 
const response_headers = {} 
// Your response body from the webhook. 
const response_body = "" 
​
// In the example here it is already a string.
const encrypted_result = Buffer.from(response_body, 'base64') 
​
const iv = Buffer.from(response_headers['x-pvt-cipher-iv'], 'base64')
const cipher = crypto.createDecipheriv('aes-256-cbc', "YOUR_WEBHOOK_SECRET", iv)
​
const decrypted_result_bytes = Buffer.concat([cipher.update(encrypted_result), cipher.final()])
const decrypted_result = decrypted_result_bytes.toString()
​
const json_result = JSON.parse(decrypted_result)
​
Server - Previous
API Reference
Next - Resources
Document image quality requirements
Last modified 8mo ago
Copy link
On this page
1. Webhook Configuration
2. Event Types
Verification Completed
Onboarding Completed
3. Security / Encryption