Event webhook

  • Updated on Mar 7, 2025

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

  1.  Make sure you have access to the Veriff Customer Portal
    1. If you do not, see the Getting Started → Sign up and Log in articles
  2.  Set up webhook URL(s) on your side and have them at hand
    1.  Make sure they match the Webhook URL requirements
    2. Make sure your system is able to handle Webhooks receipt, delivery and resending requirements
  3. Secure your communication, check the HMAC Authentication and Endpoint Security article
  4. Make sure your system is able to handle the Backwards compatible changes

5.Proceed to Decision webhook setup section below

Events webhook setup

  1. Log in to the Veriff Customer Portal

  2. Navigate to the Integrations page via the top menu and open the relevant integration

  3. On the integration's page, select the Settings tab

  4. Under the title Integration settings you see a list of webhooks

  5. 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 session

  • attemptId: string* UUID v4 which identifies session attempt

  • feature: string* Feature on which the event was triggered (selfid refers to the end-user flow)

  • code: integer* Event code, one of 7001, 7002

  • action: string* Description corresponding to the triggered event, one of started, submitted

  • vendorData: string | null* The unique identifier that you created for your end-user. null if not specified

  • endUserId: string | null* The unique UUID that you created for your end-user. null if not specified

  • context: object Object containing info about possible reasons why the end-user left the flow. Optional, depeding on the integration

    • reason: string Indicates the reason why the end-user might have left the flow

    • state: 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

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 for end-user events

Events 7007-7010 may send additional info. The payload may include a context object, containing reason and state strings (both optional).

The reason string has different values depending on the event it was sent for (see the table below)

Event name

reason value

Description

waiting_complete

final_decision_received

Session got a final decision

waiting_complete

final_decision_received_from_socket

Session got a final decision (websocket)

waiting_complete

waiting_decision_continue_clicked

The end-user clicked on the Continue button after the final decision was passed

flow_finished

finished_screen_confirmed_clicked

The end-user clicked on the Confirmed button in the "leave session dialog"

flow_cancelled

quit_session_confirmed

Sent if the end-user clicked on the Exit button in the "leave session dialog"

flow_cancelled

error_screen_exit_clicked

Sent if the end-user clicked on the Exit button in the "error screen"

flow_cancelled

consent_screen_cancel_pressed

Sent if the end-user clicked on the Cancel button on "consent screen"

flow_cancelled

mobile_handover_screen_shown

Sent on two occasions:

a) once the "mobile handover screen" is shown, only for Desktop devices (no state passed here since no screen is shown yet)

b) when video webRTC failed or an unexpected error occurred when getting end-user's camera

The state string sends a value trying to indicate the state of the end-user flow at the moment of flow stopping (e.g., because the flow was finished or abandoned). Table below lists the possible values for the string.

The "Description" column explains the type of screen the end-user sees, and whether they are prompted to take some action.

state value

Description

intro_screen_shown

The introductions screen (first screen of the flow) is shown

country_document_screen_shown

The document and country selection screen is shown

country_select_screen_shown

The country select screen is shown

document_detection_screen_shown

The screen where the end-user can select the document type is shown

document_select_screen_shown

The document select screen is shown

passport_signature_context_screen_shown

The screen with instructions how to make a passport signature picture is shown

permissions_warmup_screen_shown

End-user is informed to get ready to grant camera/microphone permissions

camera_access_blocked_screen_shown

End-user is asked to grant camera/microphone permissions, which means that these were not initially granted

barcode_scan_screen_shown

The screen to scan the barcode is shown

qr_scan_screen_shown

The screen to scan the QR-code is shown

consent_screen_shown

The consent screen is shown

doc_num_input_screen_shown

End-user is prompted to manually enter the 12-digit document number

otp_screen_shown

End-user sees the one-time password (OTP) screen where they can enter the OTP code

otp_submit_screen_shown

End-user did not see any errors after submitting their one-time password, meaning the flow has been successfully completed

mobile_handover_screen_shown

End-user sees a screen informing that they will be directed to use a mobile device for verification

mobile_handover_connecting_screen_shown

End-user sees the mobile handover screen where they are prompted to check their mobile or check their email to continue

mobile_handover_connected_screen_shown

End-user is given the option to fallback via sms or QR code. This event is triggered when the end-user tries with either method

resubmission_feedback_screen_shown

The resubmission feedback screen is shown

finished_screen_shown

The final screen of the flow is shown, where the end-user is informed that session is successfully finished

waiting_decision_screen_shown

End-user sees the "waiting decision" screen, where they are asked to wait until the final decision is made

error_screen_shown

An error screen is shown

consent_screen_shown

End-user sees the consent screen after pressing the button on the intro screen to start the session

resubmission_feedback_screen_shown

The resubmission feedback screen is shown

portrait_screen_shown

End-user sees the screen where they need to capture their selfie

document_front_screen_shown

End-user sees the screen where they need to capture the document front

document_back_screen_shown

End-user sees the screen where they need to capture the document back

document_and_face_screen_shown

End-user sees the screen where they need to capture the document front and take a selfie

barcode_screen_shown

End-user sees the screen where they need to scan the barcode

passport_screen_shown

End-user sees the screen where they need to capture their passport

poa_screen_shown

End-user sees the screen where they need to capture their Proof of Address (PoA) document

passport_signature_screen_shown

End-user sees the screen where they need to capture the passport signature

portrait_feedback_screen_shown

End-user gets feedback about the selfie taken and is asked to capture it again

document_front_feedback_screen_shown

End-user gets feedback about the image of the document front taken and is asked to capture it again

document_back_feedback_screen_shown

End-user gets feedback about the image of the document back taken and is asked to capture it again

document_and_face_feedback_screen_shown

End-user gets feedback about the image of the document and selfie taken and is asked to capture them again

barcode_feedback_screen_shown

End-user gets feedback about the barcode captured and is asked to scan it again

passport_feedback_screen_shown

End-user gets feedback about the image of the passport and is asked to capture it again

poa_feedback_screen_shown

End-user gets feedback about image of the proof of address document taken and is asked to capture it again

passport_signature_feedback_screen_shown

End-user gets feedback about the passport signature taken and is asked to capture it again

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"
}

Related articles