Webhooks
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.
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.
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"
}
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.
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"
}
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. |
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)
Last modified 10mo ago