Skip to content
On this page

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:

  1. You are using our DVFC 047 system.
  2. 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

PropertyNotes
IdThe id of the case result associated with the notification.
CaseIdCaseId of the case associated with the notification.
DVFCWebResultResult 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.

PropertyDescription
AccountIdUnique identifier for the user.
AppIdIdentifier of the App which triggered the notification. It’ll always be SDK-Web
ResourceIdThe unique identifier for the session.
ResourceTypeThe type of the resource, it’ll always be ONBOARDING.
EventThe notification event type will be either START_ONBOARDING or END_ONBOARDING
EventDateNotification creation date
EventDataNotification event data. See 1.1.1 for more information.
1.1.1 DVFCWebResult - Notification - EventData
PropertyDescription
BusinessUidThe session id.
EndpointCodeThe notification endpoint code used.
OnboardingStatusThe 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.
WithQualityIssuesFlag 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.

PropertyDescription
UidThe unique identifier for the onboarding session.
StatusOnboardingStatus as described in 1.1.1
ErrorCauseCause of the error that terminated the onboarding. See 1.2.1 for more detail.
ResultObject containing the final results of the onboarding, once it’s complete. See 1.2.2 for more details.
MessageInformation message.(Like to warn that the results are not available anymore if delay expired).
1.2.1 DVFCWebResult - OnboardingResults - ErrorCause
PropertyDescription
CodeCode 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.
DetailsMore 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
PropertyDescription
UidThe unique identifier of the onboarding.
BusinessUidThe session id for the onboarding.
StatusIndicate 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.
AnalysisResultsList 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.

PropertyDescription
CodeCode from the DocToCapture description, client defined capture identifier.
ExpectedDocTypesList of expected DocToCaptureType that should be confirmed by the analysis.
ListCapturedDocsList containing the document base64 contents that were captured, either one or both sides.
ListCapturedDocUidsList containing the document ids that were captured, either one or both sides.
BiometricConsentThe user consent for automated processing of Biometric documents (Only Selfie & Liveness).
AnalysisDataThe data extracted from the analysis. May contain OwnerData if the document carried a MRZ. See 1.2.4 for more details.
CaptureSourceSource 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
PropertyDescription
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)
WithQualityIssuesFlag to indicate if the document captured has quality issues (true).
OwnerData 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