Event webhook

Prev Next

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.

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 the action string in the payload

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

  • Tables showing the possible values for reason and state strings in the event webhook payload have been moved to a separate new article: End-user flow events (table). The lists there have been updated with new values.

  • Updated the note about 7002 submitted webhook action

Mar 12, 2025

Documentation published