W2 DocsWebhooks 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 - Initial Onboarding Result
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 - Initial Onboarding Result
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 initializedCLICKED - 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 |
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 stringBirthDate - object consisting of three integer properties: Day, Month and Year |
Sample Payload - Full Analysis Result
This webhook will be sent out when the analysis of the documents captured has been finished.
The webhook consists of an HTTP POST call with an application/JSON payload.
json
{
"Id": "xxxxxx1a-0ed6-4ef8-afe4-ceb2ac9da88f",
"CaseId": "xxxxxxfa-2f42-4812-8b89-a59661c6fd5e",
"DVFCWebResult": {
"Notification": {
"AccountId": "[email protected]",
"ResourceId": "xxxxxxc8-3bf8-4872-9744-e6a6aab31b3b",
"ResourceType": "ONBOARDING",
"Event": "END_ONBOARDING",
"EventDate": "2024-10-05T15:26:20.598+01:00[Europe/Paris]",
"EventData": {
"BusinessUid": "xxx7aefa",
"EndpointCode": "x-d-endpoint",
"OnboardingStatus": "SUCCESS",
"CisData": {
"CisFileUid": "xxxxxx6c-1541-4f49-8bbb-ae643dc97121",
"FileCheckTaskUid": "xxxxxxe0-cddb-49ea-a555-807954958a9b",
"FileCheckTaskStatus": "ONGOING",
"Realm": "namename"
}
}
},
"OnboardingResults": {
"Uid": "xxxxxxc8-3bf8-4872-9744-e6a6aab31b3b",
"Status": "SUCCESS",
"Result": {
"Uid": "xxxxxxc8-3bf8-4872-9744-e6a6aab31b3b",
"BusinessUid": "xxxxaefa",
"Status": "SUCCESS",
"AnalysisResults": [
{
"Code": "ID",
"ExpectedDocTypes": [
"P",
"DL",
"RP",
"ID"
],
"ListCapturedDocs": [
],
"ListCapturedDocUids": [
"<string>",
"<string>"
],
"AnalysisData": {
"DocType": "DL"
},
"CisData": {
"CisDocumentUid": "<string>"
}
},
{
"Code": "BIOLIVENESS",
"ExpectedDocTypes": [
"LIVENESS"
],
"ListCapturedDocs": [
],
"BiometricConsent": true,
"CisData": {
"CisDocumentUid": "<string>"
}
}
]
}
},
"FileAnalysisResults": {
"Uid": "xxxxxx6c-1541-4f49-8bbb-ae643dc97121",
"CreationDate": "2024-12-05T15:24:46+0100",
"Verdict": {
"Status": "SUCCESS"
},
"AnalysisReport": {
"ChecksPerformed": [
{
"Title": "<string>",
"Status": "OK",
"DocumentsAnalysed": [
"<string>"
],
"ChecksPerformed": [
{
"Name": "ID_ANALYSIS",
"ResonMessages": [
"The ID is OK"
],
"Status": "OK",
"SubChecks": [
{
"Name": "MODEL_RECOGNIZED",
"ResonMessages": [
"Identified document"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "DOC_SPECIMEN",
"ResonMessages": [
"This document is not a specimen"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "DOC_EXPIRATION_DATE",
"ResonMessages": [
"The document is within its validity period",
"Expected Value: , Found Value: xx/xx/xxxx"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "ID_FALSIFICATION",
"ResonMessages": [
"Document is not falsified"
],
"Status": "OK",
"SubChecks": [
{
"Name": "DOC_BLACKLISTED",
"ResonMessages": [
"No blacklist has been checked for this document"
],
"SubChecks": [
]
},
{
"Name": "EMISSION_COUNTRY",
"ResonMessages": [
"The issue country of the document is valid",
"Expected Value: , Found Value: GBR"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "EMISSION_DATE",
"ResonMessages": [
"The issue date of the document is valid",
"Expected Value: , Found Value: xx/xx/xxxx"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "DOC_NATIONALITY",
"ResonMessages": [
"The holder nationality has not been verified"
],
"SubChecks": [
]
},
{
"Name": "VALIDITY_PERIOD",
"ResonMessages": [
"The validity period of the document could not be evaluated"
],
"SubChecks": [
]
},
{
"Name": "MRZ_FIELDS_SYNTAX",
"ResonMessages": [
"The MRZ fields have not been verified"
],
"SubChecks": [
]
},
{
"Name": "MRZ_CHECKSUMS",
"ResonMessages": [
"The MRZ checksums have not been verified"
],
"SubChecks": [
]
},
{
"Name": "MRZ_EXPECTED_FOUND",
"ResonMessages": [
"No MRZ presence check"
],
"SubChecks": [
]
},
{
"Name": "OCR_FIRSTNAMES",
"ResonMessages": [
"The holder's firstnames have not been verified"
],
"SubChecks": [
]
},
{
"Name": "OCR_LASTNAME",
"ResonMessages": [
"The holder's lastname has not been verified"
],
"SubChecks": [
]
},
{
"Name": "OCR_BIRTHDATE",
"ResonMessages": [
"The holder's birthdate has not been verified"
],
"SubChecks": [
]
},
{
"Name": "OCR_DOCNUM",
"ResonMessages": [
"The document number extracted from the MRZ is consistent with the one extracted from the document"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "OCR_EXPIRATIONDATE",
"ResonMessages": [
"The expiration date consistency has not been verified"
],
"SubChecks": [
]
},
{
"Name": "OCR_EMISSIONDATE",
"ResonMessages": [
"The emit date has not been verified"
],
"SubChecks": [
]
},
{
"Name": "OCR_PERSONALNUM",
"ResonMessages": [
"The personal number has not been verified"
],
"SubChecks": [
]
},
{
"Name": "MRZ_ALIGNEMENT",
"ResonMessages": [
"The verification of the MRZ graphical format has not been done"
],
"SubChecks": [
]
},
{
"Name": "MRZ_CLASSIFIER",
"ResonMessages": [
"The verification of the consistency of the MRZ with the document model has not been done"
],
"SubChecks": [
]
},
{
"Name": "PHOTO_CONFORMITY",
"ResonMessages": [
"The detected photo is legit"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "PHOTO_LOCATION",
"ResonMessages": [
"A photo has been detected at the location indicated in the document model"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "VISUAL_SECURITY",
"ResonMessages": [
"The graphical security elements are present and valid"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "SIDES_MODEL_MATCHING",
"ResonMessages": [
"The two sides match with the same document model"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "SIDES_DATA_MATCHING",
"ResonMessages": [
"Control not done, There is either only one side or there is no redundant data between the two sides or we were not able to read them"
],
"SubChecks": [
]
}
]
},
{
"Name": "ID_ACCEPTANCE",
"ResonMessages": [
"The ID acceptance has not been checked"
],
"SubChecks": [
{
"Name": "INVALIDATED_DOCUMENT",
"ResonMessages": [
"The validity of the document has not been verified"
],
"SubChecks": [
]
},
{
"Name": "ORIGINAL_DOCUMENT",
"ResonMessages": [
"The verification that it's an original document could not be done"
],
"SubChecks": [
{
"Name": "PHOTOCOPY_DETECTION",
"ResonMessages": [
"The photocopy detection could not be done"
],
"SubChecks": [
]
},
{
"Name": "SCREEN_DETECTION",
"ResonMessages": [
"The screenshot detection could not be done"
],
"SubChecks": [
]
}
]
}
]
}
]
}
],
"DocumentsOCR": [
{
"Category": "Address",
"Label": "Full address",
"Value": "51 xa WAY, xxx, Bristol,,BS1 1NE"
},
{
"Category": "Identity",
"Label": "Birth date",
"Value": "xx/xx/xxxx"
},
{
"Category": "Identity",
"Label": "Birth day",
"Value": "xx"
},
{
"Category": "Identity",
"Label": "Birth month",
"Value": "x"
},
{
"Category": "Identity",
"Label": "Birth place",
"Value": "xx"
},
{
"Category": "Identity",
"Label": "Birth year",
"Value": "xxxx"
},
{
"Category": "Identity",
"Label": "First name",
"Value": "xxxx"
},
{
"Category": "Identity",
"Label": "Last name",
"Value": "xxxx"
}
]
},
{
"Title": "<string>",
"Status": "OK",
"ChecksPerformed": [
{
"Name": "LIVENESS_ANALYSIS",
"ResonMessages": [
"Liveness analysis is OK"
],
"Status": "OK",
"SubChecks": [
{
"Name": "CAPTURE_SESSION_CONDITIONS",
"ResonMessages": [
"The capture session went smoothly"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "CAPTURE_SESSION_QA",
"ResonMessages": [
"The quality of the session made it possible to give a verdict"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "GENUINE_VIDEO",
"ResonMessages": [
"The video seems to be genuine"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "ici4u.LIVENESS_VALIDITY",
"ResonMessages": [
"Liveness has been checked"
],
"Status": "OK",
"SubChecks": [
{
"Name": "LIVENESS_DETECTION",
"ResonMessages": [
"Liveness detected"
],
"Status": "OK",
"SubChecks": [
]
},
{
"Name": "LIVENESS_FACE_MATCHING",
"ResonMessages": [
"Face recognition succeeded"
],
"Status": "OK",
"SubChecks": [
]
}
]
}
]
}
],
"DocumentsOCR": [
]
}
]
}
}
}
}Field Breakdown - Full Analysis Result
2. Verification 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 and verification process, consisting of three parts Notification, OnboardingResults, FileAnalysisResults |
Please refer to the previous section for Notification and OnboardingResults field breakdowns.
1.3 DVFCWebResult - FileAnalysisResults
Results of the file analysis, contains overall status and the checks performed for all documents analysed.
| Property | Description |
|---|---|
| Uid | The unique identifier for the verification session. |
| CreationDate | Creation date of the verification process. |
| Verdict | Verdict. |
| AnalysisReport | The full analysis report from the verification process. |
1.3.1 DVFCWebResult - FileAnalysisResults - Verdict
The overall verdict of the verification process.
| Property | Description |
|---|---|
| Status | String - The following values are available: SUCCESS, |
REJECTED,FRAUDULENT_IDENTITY_SUSPICION,INTERNAL_ERROR,NOT_COMPLETE | |
| CauseOfRejection | String or null - The following values are available: DATA_NOT_MATCH,DOC_FIELDS_UNREADABLE,MISSING_SIDE,DOC_NOT_ORIGINAL,DOC_EXPIRED,DOC_NOT_ACCEPTED,NFC_ISSUE,VIDEO_QUALITY,MANUAL_TREATMENT_TIMEOUT |
| ErrorCauseMessage | Cause of the error. |
1.3.2 DVFCWebResult - FileAnalysisResults - AnalysisReport
The specific checks performed during the verification process.
| Property | Description |
|---|---|
| ChecksPerformed | The array of objects DocumentVerificationCheck with checks performed. The objects are grouped together by document capture sections from the onboarding. e.g. Liveness check, Document capture (DL or Passport), Document Capture (ID) |
1.3.2.1 DVFCWebResult - FileAnalysisResults - AnalysisReport - DocumentVerificationCheck
| Property | Description |
|---|---|
| Title | Identifier for the verification process. |
| Status | Overall status of the Document Analysis. |
| ChecksPerformed | Array of objects AnalysisCheck |
| DocumentsOCR | Array of objects DocumentOCR |
1.3.2.1.1 DVFCWebResult - FileAnalysisResults - AnalysisReport - DocumentVerificationCheck - ChecksPerformed - AnalysisCheck
| Property | Description |
|---|---|
| Name | Name of the check performed. |
| ResonMessages | Reasoning messages for the check. |
| Status | String - The available values: NONE,OK,WARN,ERROR,OBSOLETE |
| SubChecks | Array of objects AnalysisCheck |
1.3.2.2.1 DVFCWebResult - FileAnalysisResults - AnalysisReport - DocumentVerificationCheck - DocumentsOCR - DocumentOCR
| Property | Description |
|---|---|
| Category | Category of the OCR. |
| Label | Specific OCR name. |
| Value | String - The OCR extracted. |