This webhook is optional and should be configured if you are interested in getting info about the progress of the verification data gathering.
If you decide to configure the webhook, you need to set Webhook events URL
up in the Veriff Customer Portal.
→ See Webhooks Guide > Set up webhooks sub-section for detailed overview of the setup process
When is event webhook sent?
Veriff uses the event webhook to pass data about the verification session status change from “started” to “submitted”. The payload is sent to Webhook events URL
and it tracks the events happening in the identity verification process performed by the end-user.
It does not provide info about the decision of the verification.
Prerequisites
- Make sure you have access to the Veriff Customer Portal
- Set up webhook URL(s) on your side and have them at hand
- Make sure they match the Webhook URL requirements
- Make sure your system is able to handle Webhooks receipt, delivery and resending requirements
- Secure your communication, check the HMAC Authentication and Endpoint Security article
- Make sure your system is able to handle the Backwards compatible changes
5.Proceed to Decision webhook setup section below
Events webhook setup
Log in to the Veriff Customer Portal
Navigate to the Integrations page via the top menu and open the relevant integration
On the integration's page, select the Settings tab
Under the title Integration settings you see a list of webhooks
Fill in the
Webhook events URL
→ See Webhooks Guide > Set up webhooks sub-section for detailed overview of the setup process
Sample request
{
"id": "f04bdb47-d3be-4b28-b028-a652feb060b5",
"attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
"feature": "selfid",
"code": 7002,
"action": "submitted",
"vendorData": "12345678",
"endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4"
}
Request properties explained
id
:string
* UUID v4 which identifies the verification sessionattemptId
:string
* UUID v4 which identifies session attemptfeature
:string
* Feature on which the event was triggered (selfid
refers to the end-user flow)code
:integer
* Event code, one of7001
,7002
action
:string
* Description corresponding to the triggered event, one ofstarted
,submitted
vendorData
:string | null
* The unique identifier that you created for your end-user.null
if not specifiedendUserId
:string | null
* The unique UUID that you created for your end-user.null
if not specifiedcontext
:object
Object containing info about possible reasons why the end-user left the flow. Optional, depeding on the integrationreason
:string
Indicates the reason why the end-user might have left the flowstate
:string
Indicates the state of the end-user flow at the moment of flow stopping
*Required field
Possible events over the webhook
7007-7010 events can be received only when you are using Veriff's web flow, and these require some additional configuration on Veriff side.
Contact your solutions engineer for info and configuration.
Webhook code | Webhook action | Description | Available | Configuration to receive events | "Waiting for decision" page enabled |
---|---|---|---|---|---|
7001 | started | The end-user arrives to Veriff verification flow and starts the verification process | via API and SDK/Web | Not needed | Not needed |
7002 | submitted | The end-user is done with the process and submits the attempt. This webhook is sent before the end-user is directed to the callback URL specified on session creation (if applicable). | via API and SDK/Web | Not needed | Not needed |
7007 | waiting_complete | The end-user gets the decision on the "waiting for decision" page | Web only | Yes, required | Yes, required |
7008 | waiting_continued | The end-user clicks on the Continue button on the "waiting for decision" page before the decision is available. This triggers the action that you have configured for the case when the end-user finishes the flow. | Web only | Yes, required | Yes, required |
7009 | flow_finished | The end-user reached the final screen and clicked on the Continue button | Web only | Yes, required | Not needed |
7010 | flow_cancelled | The end-user abandons the verification flow | Web only | Yes, required | Not needed |
7011 | document_type_other_selected | The end-user indicates that they want to use another document type for verification | Web only | Yes, required | Not needed |
There are also events which we do not notify about. Log in to your Veriff account and see the Verification statuses and decisions meaning[↗] article In Veriff Knowledge Base for more info.
Additional info about end-user events
Events 7007-7010 may send additional info. The payload may include:
action
string, naming the webhook action (see the table above)
a
context
object, containing the optional:reason
string, which gives some context to theaction
string in the payloadstate
strings, which tries to indicate the state of the end-user flow at the moment of flow stopping (e.g., because the flow was finished or abandoned)
→ See the End-user flow events (table) article for lists of possible reason
and state
values
Sample request when the end-user received the decision on the "waiting for decision" page
{
"id": "f04bdb47-d3be-4b28-b028-a652feb060b5",
"attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
"feature": "selfid",
"code": 7007,
"action": "waiting_complete",
"context": {
"reason": "final_decision_received"
},
"vendorData": "QWE123",
"endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4"
}
Sample request when the end-user finished the flow
{
"id": "f04bdb47-d3be-4b28-b028-a652feb060b5",
"attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
"feature": "selfid",
"code": 7009,
"action": "flow_finished",
"context": {
"reason": "finished_screen_confirmed_clicked",
"state": "finished_screen_shown"
},
"vendorData": "QWE123",
"endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4"
}
Sample request when the end-user abandoned the flow
{
"id": "f04bdb47-d3be-4b28-b028-a652feb060b5",
"attemptId": "e30122d1-740b-4764-853f-470374a7abf4",
"feature": "selfid",
"code": 7010,
"action": "flow_cancelled",
"context": {
"reason": "quit_session_confirmed",
"state": "camera_access_blocked_screen_shown"
},
"vendorData": "QWE123",
"endUserId": "a1b2c35d-e8f7-6d5e-3cd2-a1b2c35db3d4"
}
Article versioning
Date | Description |
---|---|
May 7, 2025 |
|
Mar 12, 2025 | Documentation published |