Event webhook

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.

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

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

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.

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