Webhooks in simple terms, are the way all the decisions and events are communicated by Veriff.
Although there's more to come in the future, we currently have 4 different types of webhooks, and they are:
Event webhook - where we post events during the lifecycle of a verification
Decision webhook - where we post decisions about verifications
Watchlist screening webhook - where we post events related to both the initial and monitored results of the PEP, sanctions, and adverse media checks.
Transportation Registry webhook(if applicable) - where we send the result of a driver’s license registry answer (valid, invalid, not supported, inconclusive)
For PEP and Sanctions Webhook, it's important to note that It is sent when PEP&Sanction checks have been conducted. This webhook is sent independent of Event and Decision Webhooks described above. For payload details, please check our Watchlist screening webhook documentation.
When are Webhooks Triggered?
If the status of a verification session changes, an event webhook will be sent out. When the final decision is made, a decision webhook with all the related data is sent to you. Some services, such as PEP and Sanctions and Proof of Address have separate webhooks. When your account has the proof of address feature enabled, a successful proof of address webhook will be sent out.
Webhooks can also be viewed in the Back Office in the verification session view. From there, if necessary, all the webhooks can also be resent.
You can receive a specific decision with a decision webhook when testing our services (in Test Integration). For the testing, simply enter the decision you want to receive along with the decision webhook next to the "First Name" field in the payload when creating a session. You can enter "Approved", "Resubmission" or "Decline" depending on the decision you want to get.
Webhook Codes
The event webhook's code can be one of the following:
7001 - Started: the verification session has been accessed by the customer but has not been yet submitted for a review.
7002 - Submitted: the verification session has been submitted to Veriff and we are in the process of verifying the customer
The Decision webhook's code can be one of the following:
9001 - Positive: the customer was verified, the process was completed correctly and the decision is "Approved".
9102 - Negative: the customer was not verified, the process was completed but the verification is "Declined".
9103 - Resubmitted: the customer was asked for a resubmission, as something was missing and Veriff was not able to give a conclusive decision.
9104 - Negative: the verification session has expired. If the customer has accessed the verification session but did not finish the process, the status will be "Abandoned". In case the customer never arrived in our environment, the status will be "Expired".
The Proof of address webhook’s event code can be:
9201 - Success: the customer address details were extracted, and the document issue date was more than 90 days ago.
Resending Webhooks
When we don’t receive a successful response from client’s backend. This is typically undelivered webhook behaviour. → In such instances, we will re-send the failed webhook for up to a week. Resending automatically stops soon as there's a successful response.
You can read more about webhooks in our API documentation.
We strongly encourage you to use SSL for webhook endpoints in Live environment, as sensitive data is being transmitted.