# Face Authentication webhooks

The [Face Authentication](https://www.checkout.com/docs/business-operations/manage-identities/authenticate-with-biometrics.md) solution sends webhooks for the following event types:

Successful authentication:
- `face_authentication_created`
- `face_authentication_opened`
- `face_authentication_started`
- `face_authentication_capture_completed`
- `face_authentication_checks_completed`

Unsuccessful authentication:
- `face_authentication_link_expired`
- `face_authentication_capture_refused`
- `face_authentication_capture_aborted`
- `face_authentication_retry_requested`
- `face_authentication_reset`
- `face_authentication_checks_inconclusive`
- `face_authentication_closed`

After the authentication:
- `face_authentication_audit_completed`
- `face_authentication_anonymized`

---

## Example webhooks

### Successful authentication

**Created**

```json
{
  "id": "evt_wulgj7iilg2u3lweve5g7oc5xa",
  "type": "face_authentication_created",
  "version": "1.2.0",
  "created_on": "2024-12-05T17:48:25.999831Z",
  "data": {
    "applicant_id": "aplt_01jebyzk8nz6j206x4hr02xywj",
    "external_applicant_id": "eaplt_10000000000000000000000000",
    "status": "created",
    "face_authentication_id": "fav_01jebyzxdkj4e2mktk36q0fpak",
    "response_codes": [],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_wulgj7iilg2u3lweve5g7oc5xa"
    }
  }
}
```

**Opened**

```json
{
  "id": "evt_p62rw5x25mhebf6le52y4xndgu",
  "type": "face_authentication_opened",
  "version": "1.2.0",
  "created_on": "2024-12-05T17:54:27.304558Z",
  "data": {
    "applicant_id": "aplt_01jebzam5y1x8jthps5pq28r27",
    "external_applicant_id": "eaplt_10000000000000000000000000",
    "status": "pending",
    "face_authentication_id": "fav_01jebzasy9p8x0n71vgkdq9pty",
    "response_codes": [],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_p62rw5x25mhebf6le52y4xndgu"
    }
  }
}
```

**Started**

```json
{
  "id": "evt_kk64am5phizezjutnsileh4tme",
  "type": "face_authentication_started",
  "version": "1.2.0",
  "created_on": "2024-12-05T17:55:01.839629Z",
  "data": {
    "applicant_id": "aplt_01jebzam5y1x8jthps5pq28r27",
    "external_applicant_id": "eaplt_10000000000000000000000000",
    "status": "capture_in_progress",
    "face_authentication_id": "fav_01jebzasy9p8x0n71vgkdq9pty",
    "response_codes": [],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_kk64am5phizezjutnsileh4tme"
    }
  }
}
```

**Capture completed**

```json
{
  "id": "evt_tbw7iyl5aitedcxgpgj73hujwu",
  "type": "face_authentication_capture_completed",
  "version": "1.2.0",
  "created_on": "2024-12-05T17:56:02.78231Z",
  "data": {
    "applicant_id": "aplt_01jebzam5y1x8jthps5pq28r27",
    "external_applicant_id": "eaplt_10000000000000000000000000",
    "status": "checks_in_progress",
    "face_authentication_id": "fav_01jebzasy9p8x0n71vgkdq9pty",
    "response_codes": [],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_tbw7iyl5aitedcxgpgj73hujwu"
    }
  }
}
```

**Checks completed**

```json
{
  "id": "evt_crprj7gximoejcqo65fm2phnha",
  "type": "face_authentication_checks_completed",
  "version": "1.2.0",
  "created_on": "2024-12-05T17:57:00.588067Z",
  "data": {
    "applicant_id": "aplt_01jebzam5y1x8jthps5pq28r27",
    "external_applicant_id": "eaplt_10000000000000000000000000",
    "status": "approved",
    "face_authentication_id": "fav_01jebzasy9p8x0n71vgkdq9pty",
    "response_codes": [
      {
        "code": 10000,
        "summary": "approved"
      }
    ],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_crprj7gximoejcqo65fm2phnha"
    }
  }
}
```

### Unsuccessful authentication

**Link expired**

```json
{
  "id": "evt_6wld3spaaa6evlvb4bovk5r57m",
  "type": "face_authentication_link_expired",
  "version": "1.2.0",
  "created_on": "2024-12-05T17:49:03.890067Z",
  "data": {
    "applicant_id": "aplt_01jeby3q6qd5zgrdttnzfsx5wj",
    "status": "retry_required",
    "face_authentication_id": "fav_01jeby3q8kzbeayxc0whnjts8k",
    "response_codes": [
      {
        "code": 61101,
        "summary": "applicant_never_started"
      }
    ],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_6wld3spaaa6evlvb4bovk5r57m"
    }
  }
}
```

**Capture refused**

```json
{
  "id": "evt_6wld3spaaa6evlvb4bovk5r57m",
  "type": "face_authentication_capture_refused",
  "version": "1.2.0",
  "created_on": "2024-12-05T17:49:03.890067Z",
  "data": {
    "applicant_id": "aplt_01jeby3q6qd5zgrdttnzfsx5wj",
    "status": "refused",
    "face_authentication_id": "fav_01jeby3q8kzbeayxc0whnjts8k",
    "response_codes": [
      {
        "code": 63001,
        "summary": "applicant_refusal"
      }
    ],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_6wld3spaaa6evlvb4bovk5r57m"
    }
  }
}
```

**Capture abandoned**

```json
{
  "id": "evt_wqhgmnsx734unhl67hcpnxeyiq",
  "type": "face_authentication_capture_aborted",
  "version": "1.2.0",
  "created_on": "2024-12-05T18:04:00.334629Z",
  "data": {
    "applicant_id": "aplt_01jebzt00z21ac7v8mf2hvs0ec",
    "external_applicant_id": "eaplt_61203A62103000000000000000",
    "status": "retry_required",
    "face_authentication_id": "fav_01jebzt41x6h42jnbg0913vv4k",
    "response_codes": [
      {
        "code": 61203,
        "summary": "camera_not_found"
      }
    ],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_wqhgmnsx734unhl67hcpnxeyiq"
    }
  }
}
```

**Retry requested**

```json
{
  "id": "evt_mtxycs5dgewunh6gil5i6qkbmm",
  "type": "face_authentication_retry_requested",
  "version": "1.2.0",
  "created_on": "2024-12-05T18:05:21.688373Z",
  "data": {
    "applicant_id": "aplt_01jebzt00z21ac7v8mf2hvs0ec",
    "external_applicant_id": "eaplt_61203A62103000000000000000",
    "status": "pending",
    "face_authentication_id": "fav_01jebzt41x6h42jnbg0913vv4k",
    "response_codes": [],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_mtxycs5dgewunh6gil5i6qkbmm"
    }
  }
}
```

**Reset**

```json
{
  "id": "evt_jcvzpnvptblevo2fpxztv5l3cy",
  "type": "face_authentication_reset",
  "version": "1.2.0",
  "created_on": "2024-12-05T18:10:08.518738Z",
  "data": {
    "applicant_id": "aplt_01jebzt00z21ac7v8mf2hvs0ec",
    "external_applicant_id": "eaplt_61203A62103000000000000000",
    "status": "pending",
    "face_authentication_id": "fav_01jec06pzg8b4zf0bnqmdfp4ew",
    "response_codes": [],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_jcvzpnvptblevo2fpxztv5l3cy"
    }
  }
}
```

**Checks inconclusive**

```json
{
  "id": "evt_axyxlxk7f34epdjxgmacmn4bge",
  "type": "face_authentication_checks_inconclusive",
  "version": "1.2.0",
  "created_on": "2024-12-05T18:28:00.835783Z",
  "data": {
    "applicant_id": "aplt_01jec137ejpfr42eze4y46hs9g",
    "external_applicant_id": "eaplt_61411I10000000000000000000",
    "status": "retry_required",
    "face_authentication_id": "fav_01jec13b0w7rxkarqarmx1jq6z",
    "response_codes": [
      {
        "code": 61411,
        "summary": "face_partially_hidden"
      }
    ],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_axyxlxk7f34epdjxgmacmn4bge"
    }
  }
}
```

**Closed**

```json
{
  "id": "evt_wqhgmnsx734unhl67hcpnxeyiq",
  "type": "face_authentication_closed",
  "version": "1.2.0",
  "created_on": "2024-12-05T18:04:00.334629Z",
  "data": {
    "applicant_id": "aplt_01jebzt00z21ac7v8mf2hvs0ec",
    "external_applicant_id": "eaplt_61203A62103000000000000000",
    "status": "retry_required",
    "face_authentication_id": "fav_01jebzt41x6h42jnbg0913vv4k",
    "response_codes": [
      {
        "code": 64001,
        "summary": "forcibly_closed"
      }
    ],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_wqhgmnsx734unhl67hcpnxeyiq"
    }
  }
}
```

### After the authentication

**Audit completed**

```json
{
  "id": "evt_uqyk4lgloeduvarejyl2we7y5y",
  "type": "face_authentication_audit_completed",
  "version": "1.2.0",
  "created_on": "2024-12-05T18:32:39.39415Z",
  "data": {
    "applicant_id": "aplt_01jec137ejpfr42eze4y46hs9g",
    "external_applicant_id": "eaplt_61411I10000000000000000000",
    "status": "approved",
    "face_authentication_id": "fav_01jec13b0w7rxkarqarmx1jq6z",
    "response_codes": [
      {
        "code": 10000,
        "summary": "approved"
      }
    ],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_uqyk4lgloeduvarejyl2we7y5y"
    }
  }
}
```

**Anonymized**

```json
{
  "id": "evt_uqyk4lgloeduvarejyl2we7y5y",
  "type": "face_authentication_anonymized",
  "version": "1.2.0",
  "created_on": "2024-12-05T18:32:39.39415Z",
  "data": {
    "applicant_id": "aplt_01jec137ejpfr42eze4y46hs9g",
    "external_applicant_id": "eaplt_61411I10000000000000000000",
    "status": "approved",
    "face_authentication_id": "fav_01jec13b0w7rxkarqarmx1jq6z",
    "response_codes": [
      {
        "code": 10000,
        "summary": "approved"
      }
    ],
    "user_journey_id": "usj_01heqt35wmjrf3wjd7w1wz33p2"
  },
  "_links": {
    "self": {
      "href": "https://{prefix}.api.checkout.com/workflows/events/evt_uqyk4lgloeduvarejyl2we7y5y"
    }
  }
}
```

---

## Webhook fields

| Field name | Description |
| --- | --- |
| `id`<br>`string` | The event's unique identifier, prefixed with `evt_`. |
| `type`<br>`string` | The event type. |
| `version`<br>`string` | The webhook's version. |
| `created_on`<br>`date-time` | The date and time when the event occurred, in UTC. <br>Standard – ISO 8601 code <br>Format – `yyyy-mm-ddThh:mm:ss.sss` |
| `data`<br>`object` | The webhook message. |
| `data.`<br>`applicant_id`<br>`string` | The applicant's unique identifier, prefixed with `aplt_`. |
| `data.`<br>`external_applicant_id`<br>`string` | Your unique identifier for the applicant, prefixed with `eaplt_`. |
| `data.`<br>`status`<br>`string` | The [authentication status](https://www.checkout.com/docs/developer-resources/codes/identities-codes.md#Check_statuses). |
| `data.`<br>`face_authentication_id`<br>`string` | The authentication's unique identifier, prefixed with `fav`. |
| `data.`<br>`response_codes`<br>`object` | The response code providing more information.<br><br>This is returned for the following events:<br><br>- `face_authentication_checks_completed`<br>- `face_authentication_report_created`<br>- `face_authentication_capture_refused`<br>- `face_authentication_link_expired`<br>- `face_authentication_capture_aborted`<br>- `face_authentication_checks_inconclusive`<br>- `face_authentication_anonymized`<br>- `face_authentication_audit_completed`<br>- `face_authentication_closed` |
| `data.`<br>`response_codes.`<br>`code`<br>`integer` | The [response code](https://www.checkout.com/docs/developer-resources/codes/identities-codes.md#Response_codes). |
| `data.`<br>`response_codes.`<br>`summary`<br>`string` | The summary that explains the response code. |
| `data.`<br>`user_journey_id`<br>`string` | Your Face Authentication [configuration ID](https://www.checkout.com/docs/business-operations/manage-identities/authenticate-with-biometrics/using-the-api.md#Configuration). |
| `_links.self.href`<br>`string` | The URL to the event. |