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:

End of Support (EoS): October 1, 2026

End of Life (EoL) / Retirement: April 1, 2027

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:

Overview

Module configuration

Face Authentication webhook

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

The following image shows sample notification payloads for several kinds of failed attempts.

{  
"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.