Authentication Webhook 1:1

Warning

This method of Face Authentication is being deprecated in favor of an updated method that uses a Face Authentication module within Workflows and Flows. This change allows for a higher level of security and configurability when authenticating users.

Key dates:

We recommend completing your migration by January 1, 2027 to avoid any last-minute issues or service disruptions.

Documentation for the new method of Face Authentication can be found here:

This webhook only triggers during 1:1 authentications. It delivers notifications for both successful and failed attempts. This page provides example payloads for this webhook.

Success Notification

The following code block shows an example of a payload for a successful attempt.

{
  "customerId": "67460a9995516d9a553aa95b",
  "token": "",
  "interviewId": "60000a22b09a35d2ef5aaa99",
  "interviewToken": "",
  "transactionId": "549994d9r3474bfcbbbdc5a5",
  "faceMatch": true,
  "spoofAttempt": false,
  "secondFactor": false,
  "children": [],
  "hasFaceMask": false,
  "hasLenses": false,
  "spoofConfidence": 0.0010233838,
  "recognitionConfidence": {
    "confidence": 0.93098663,
    "candidates": []
  },
  "overallScore": 0.93098663,
  "overallStatus": "PASS"
}

Failure Notifications

Note

Authentication attempts can fail as a result of the user wearing lenses, a mask, or a hat. These are not considered errors, and no additional ‘error’ fields are sent within the notification.

The payload for a failed attempt includes 3 fields (shown in the table headings) with information about the error. The field values vary depending on the error.

error errorCode errorMessage
User blacklisted 4003 NA
Non existing customer 4004 Can't find customer by any criteria
Spoof attempt detected 4005 Spoof attempt detected. Spoof confidence 1.0
User is not recognized 4015 NA 
{
  "customerId": "666eab5555888d45ba7a999a",
  "faceMatch": false,
  "children": [],
  "recognitionConfidence": {},
  "overallScore": 0,
  "overallStatus": "FAIL",
  "error": "Non existing customer",
  "errorCode": 4004,
  "errorMessage": "Can't find customer by any criteria."
}

{
  "customerId": "67dda40e4089f4769f3ed2e6",
  "transactionId": "e59ee5a064e24d129d1beed9",
  "faceMatch": false,
  "spoofAttempt": true,
  "children": [],
  "spoofConfidence": 1,
  "recognitionConfidence": {},
  "overallScore": 0,
  "overallStatus": "FAIL",
  "error": "Spoof attempt detected",
  "errorCode": 4005,
  "errorMessage": "Spoof attempt detected. Spoof confidence 1.0"
}

{
  "customerId": "678057dbb632b29f45a280b5",
  "transactionId": "18e69943c68a4f5e89d61857",
  "faceMatch": false,
  "spoofAttempt": false,
  "children": [],
  "spoofConfidence": 0.00085131516,
  "recognitionConfidence": {},
  "overallScore": 0,
  "overallStatus": "FAIL",
  "error": "User is not recognized",
  "errorCode": 4015
}

{
  "customerId": "666eab5555888d45ba7a999a",
  "faceMatch": false,
  "children": [],
  "recognitionConfidence": {},
  "overallScore": 0,
  "overallStatus": "FAIL",
  "error": "User blacklisted",
  "errorCode": 4003
}

{
  "customerId": "67dda40e4089f4769f3ed2e6",
  "transactionId": "0be5f261d076492d9d3b74f6",
  "faceMatch": false,
  "spoofAttempt": false,
  "hasFaceMask": false,
  "hasLenses": true,
  "recognitionConfidence": {
    "confidence": 0,
    "candidates": []
  },
  "overallScore": 0,
  "overallStatus": "FAIL"
}

{
  "customerId": "67dda40e4089f4769f3ed2e6",
  "transactionId": "0be5f261d076492d9d3b74f6",
  "faceMatch": false,
  "spoofAttempt": false,
  "hasFaceMask": true,
  "hasLenses": false,
  "recognitionConfidence": {
    "confidence": 0,
    "candidates": []
  },
  "overallScore": 0,
  "overallStatus": "FAIL"
}

Alert

Notifications are also sent for any Incode API exception or unpredicted error. In these cases, the errorCode, error, and errorMessage fields are added to the payload but exact values are not available.