### 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](https://developer.incode.com/docs/face-authentication-overview)
- [Module configuration](https://developer.incode.com/docs/face-authentication-module)
- [Face Authentication webhook](https://developer.incode.com/docs/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.

```json
{
  "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 |

```json
{
  "customerId": "666eab5555888d45ba7a999a",
  "faceMatch": false,
  "children": [],
  "recognitionConfidence": {},
  "overallScore": 0,
  "overallStatus": "FAIL",
  "error": "Non existing customer",
  "errorCode": 4004,
  "errorMessage": "Can't find customer by any criteria."
}
```

```json
{
  "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"
}
```

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

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

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

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