Webhooks for DVFC (Alpha)

⚠️ Alpha: Please note webhooks are in an early stage of development and are subject to change.

Purpose

Our DVFC Alert webhooks have been created to trigger a webhook whenever an Alert is generated from our verification system. This will enable you to utilise any downstream automation like updates to ongoing verification checks.

Getting Set Up

Our Webhooks are an important new feature of our Document Verification & Facial Recognition, in order to make use of them you will need to ensure:

You are using our DVFC 047 system.
You have informed us of the callback URL you are listening on.

To establish either of these you can reach out to our Support team who can help you get started.

Sample Payload

The webhook consists of an HTTP POST call with an application/JSON payload.

json

{
  "id" : "case-result-guid",
  "caseId" : "case-id-guid",
  "dvfcWebResult" : {
    "notification" : {
      "accountId" : "user.sdkweb.cis",
      "resourceId" : "26324621-2688-47c4-904d-3cbc07ed4a56",
      "resourceType" : "ONBOARDING",
      "event" : "END_ONBOARDING",
      "eventDate" : "2017-07-21T17:32:28Z",
      "eventData" : {
        "businessUid" : "sessionId",
        "endpointCode" : "notify-endpoint",
        "onboardingStatus" : "SUCCESS",
        "withQualityIssues" : "true"
      }
    },
    "onboardingResults" : {
      "uid" : "guid-of-the-onboarding",
      "status" : "SUCCESS",
      "errorCause" : {
        "code" : "USER_ERROR",
        "details" : "More details about the origin of the error"
      },
      "result" : {
        "uid" : "guid-of-the-onboarding",
        "businessId" : "sessionId",
        "status" : "SUCCESS",
        "analysisResults" : [
          {
            "code" : "code from the document definition",
            "expectedDocTypes" : [
              "ID", "P"
            ],
            "listCapturedDocs" : [
              "base-64 contents that were captured"
            ],
            "listCapturedDocUids" : [
              "list of document ids that were captured"
            ],
            "biometricConsent" : true,
            "analysisData" : {
              "docType" : "P",
              "withQualityIssues" : true,
              "owner" : { // only extracted from MRZ documents
                "lastNames" : [
                  "lastName"
                ],
                "firstNames" : [
                  "firstNames"
                ],
                "birthDate" : {
                  "day" : 1,
                  "month" : 10,
                  "year" : 1990
                }
              }
            },
            "captureSource" : "NATIVE_CAMERA"
          }
        ],
        "extraData" : {
          "missingOptionalDocs" : [
            "List of the optional documents codes that the user chose not to capture"
          ],
          "device" : {
            "userAgent" : "user-agent of the browser used to do the onboarding"
          }
        }
      },
      "message" : "Information message.(Like to warn that the results are not available anymore if delay expired)."
    }
  }
}

Field Breakdown

1. Identification Process

Property	Notes
Id	The id of the case result associated with the notification.
CaseId	CaseId of the case associated with the notification.
DVFCWebResult	Result of the identification process, consisting of two parts `Notification` and `OnboardingResults`

1.1 DVFCWebResult - Notification

This section of the result will contain information about the type of the notification and the general status of the identification session.

Property	Description
AccountId	Unique identifier for the user.
AppId	Identifier of the App which triggered the notification. It’ll always be SDK-Web
ResourceId	The unique identifier for the session.
ResourceType	The type of the resource, it’ll always be `ONBOARDING`.
Event	The notification event type will be either `START_ONBOARDING` or `END_ONBOARDING`
EventDate	Notification creation date
EventData	Notification event data. See 1.1.1 for more information.

1.1.1 DVFCWebResult - Notification - EventData

Property	Description
BusinessUid	The session id.
EndpointCode	The notification endpoint code used.
OnboardingStatus	The overall status of the identification process. Can be one of the following: `CREATED` - the session onboarding was initialized `CLICKED` - the user reached the onboarding starting page `CAPTURE_ONGOING` - the user captured at least one document but did not yet complete the onboarding `SUCCESS` - the onboarding was completed `EXPIRED` - the onboarding expired before the user completed it and was automatically closed `ERROR` - the onboarding was terminated because of an error, see `ErrorCause`.
WithQualityIssues	Flag to indicate if at least one document captured has quality issues (true). This happens when the user is not able to push an issue less document after several tries.

1.2 DVFCWebResult - OnboardingResults

Status of the onboarding, contains results as well if the onboarding reached the end.

Property	Description
Uid	The unique identifier for the onboarding session.
Status	OnboardingStatus as described in 1.1.1
ErrorCause	Cause of the error that terminated the onboarding. See 1.2.1 for more detail.
Result	Object containing the final results of the onboarding, once it’s complete. See 1.2.2 for more details.
Message	Information message.(Like to warn that the results are not available anymore if delay expired).

1.2.1 DVFCWebResult - OnboardingResults - ErrorCause

Property Description

Code Code of the error that terminated the onboarding. Can be one of the following:
NETWORK_ERROR - Connectivity error
USER_ERROR - Related to a user action
DEVICE_ERROR - Related to the device’s capabilities (unsupported browser, camera…)
DOCUMENT_ERROR - Related to the document pushed by user(rejected, unidentified…)
INTERNAL_ERROR - There was an unexpected technical error during the onboarding.

Details More details about the origin of the error. Can be one of the following messages:
WRONG_TYPE - The document was identified but did not match the expected types(outside PVID).
MODEL_REJECTED - The document was identified but did not match the eligible types(based on Customer Configuration filtering list).
ANALYSIS_EXPIRED_DOC - The document was identified but its expiration date is not valid.
UNIDENTIFIED - The document was not identified.
INVALID_VERSO The verso is not compatible with recto.
NO_FACE - The document do not have the needed Face.
DOC_NOT_USABLE_FACEREC - (outside PVID) The document is not eligible for Biometric check.
PVID_NOT_ELIGIBLE - IPS The document is not eligible for PVID Onboarding.
ETSI_NOT_ELIGIBLE - IPS The document is not eligible for ETSI Onboarding.
QUALITY_ISSUES - (outside PVID).
OPENTOK_API_ERROR - (outside PVID).
SESSION_CLOSED_BY_USER - Session closed by user.
NETWORK_TOO_SLOW_ERROR - Network too slow.
DEVICE_ROTATED_ERROR - Device rotated.
CAMERA_NOT_FOUND - No camera detected.
CAMERA_ACCESS_DENIED - Access to camera is forbidden.
CAMERA_ACCESS_TIMEOUT - Timeout while trying to get camera access.
CAMERA_NOT_READABLE - Camera already used by another application.
BROWSER_NOT_SUPPORTED - Browser or device not supported.
NO_AUDIO_DETECTED - (outside PVID) Invalid video.
VIDEO_ERROR - Video quality error (resolution or framerate too low).
ONBOARDING_ALREADY_CONSUMED - User tries to launch a link of an onboarding already started

Property	Description
Code	Code of the error that terminated the onboarding. Can be one of the following: `NETWORK_ERROR` - Connectivity error `USER_ERROR` - Related to a user action `DEVICE_ERROR` - Related to the device’s capabilities (unsupported browser, camera…) `DOCUMENT_ERROR` - Related to the document pushed by user(rejected, unidentified…) `INTERNAL_ERROR` - There was an unexpected technical error during the onboarding.
Details	More details about the origin of the error. Can be one of the following messages: `WRONG_TYPE` - The document was identified but did not match the expected types(outside PVID). `MODEL_REJECTED` - The document was identified but did not match the eligible types(based on Customer Configuration filtering list). `ANALYSIS_EXPIRED_DOC` - The document was identified but its expiration date is not valid. `UNIDENTIFIED` - The document was not identified. `INVALID_VERSO` The verso is not compatible with recto. `NO_FACE` - The document do not have the needed Face. `DOC_NOT_USABLE_FACEREC` - (outside PVID) The document is not eligible for Biometric check. `PVID_NOT_ELIGIBLE` - IPS The document is not eligible for PVID Onboarding. `ETSI_NOT_ELIGIBLE` - IPS The document is not eligible for ETSI Onboarding. `QUALITY_ISSUES` - (outside PVID). `OPENTOK_API_ERROR` - (outside PVID). `SESSION_CLOSED_BY_USER` - Session closed by user. `NETWORK_TOO_SLOW_ERROR` - Network too slow. `DEVICE_ROTATED_ERROR` - Device rotated. `CAMERA_NOT_FOUND` - No camera detected. `CAMERA_ACCESS_DENIED` - Access to camera is forbidden. `CAMERA_ACCESS_TIMEOUT` - Timeout while trying to get camera access. `CAMERA_NOT_READABLE` - Camera already used by another application. `BROWSER_NOT_SUPPORTED` - Browser or device not supported. `NO_AUDIO_DETECTED` - (outside PVID) Invalid video. `VIDEO_ERROR` - Video quality error (resolution or framerate too low). `ONBOARDING_ALREADY_CONSUMED` - User tries to launch a link of an onboarding already started

1.2.2 DVFCWebResult - OnboardingResults - Result

Property	Description
Uid	The unique identifier of the onboarding.
BusinessUid	The session id for the onboarding.
Status	Indicate if the onboarding was successful or not. `SUCCESS` - capture was successful, analysis results are available. `ERROR` - there was an error during the capture or while pushing the captured document, see ErroCause.
AnalysisResults	List of AnalysisResult objects containing the analysis results extracted from a document. See 1.2.3 for more details.

1.2.3 DVFCWebResult - OnboardingResults - AnalysisResult

Contains the analysis results extracted for a document.

Property	Description
Code	Code from the DocToCapture description, client defined capture identifier.
ExpectedDocTypes	List of expected `DocToCaptureType` that should be confirmed by the analysis.
ListCapturedDocs	List containing the document base64 contents that were captured, either one or both sides.
ListCapturedDocUids	List containing the document ids that were captured, either one or both sides.
BiometricConsent	The user consent for automated processing of Biometric documents (Only Selfie & Liveness).
AnalysisData	The data extracted from the analysis. May contain OwnerData if the document carried a MRZ. See 1.2.4 for more details.
CaptureSource	Source of the captured document. Can be one of the following: - `WIDGET_CAMERA` : Capture has been done with a camera inside the browser(automatic capture). - `NATIVE_CAMERA` : Capture has been done with a native camera outside the browser. - `UPLOAD` : Document has been uploaded from the device. - `UNKNOWN` : Mobile user chose between `NATIVE_CAMERA` or `UPLOAD` and we don’t know the capture source.

1.2.4 DVFCWebResult - OnboardingResults - AnalysisData

Property	Description
DocType	- `ID` national identity card - `P` passport - `V` visa - `DL` driving license - `HC` health card - `RP` resident permit - `SELFIE` picture of user - `LIVENESS` Liveness detection - `CAR_REG` car registration - `KBIS` company registration (not analysed) - `RIB` bank account identity (not analysed) - `ADR_PROOF` residence certificate (not analysed) - `PAY_SHEET` remuneration statement (not analysed) - `TAX_SHEET` tax bill (not analysed) - `OTHER` other type of document (not analysed)
WithQualityIssues	Flag to indicate if the document captured has quality issues (true).
Owner	Data related to the document owner (Only extracted from MRZ documents). The object consists of: `LastNames` - list of strings, `FirstNames` - list of string `BirthDate` - object consisting of three integer properties: `Day`, `Month` and `Year`

Webhooks for DVFC (Alpha) ​

Purpose ​

Getting Set Up ​

Sample Payload ​

Field Breakdown ​

1. Identification Process ​

1.1 DVFCWebResult - Notification ​

1.1.1 DVFCWebResult - Notification - EventData ​

1.2 DVFCWebResult - OnboardingResults ​

1.2.1 DVFCWebResult - OnboardingResults - ErrorCause ​

1.2.2 DVFCWebResult - OnboardingResults - Result ​

1.2.3 DVFCWebResult - OnboardingResults - AnalysisResult ​

1.2.4 DVFCWebResult - OnboardingResults - AnalysisData ​