Create a Liveness Check

A liveness check evaluates whether the captured face belongs to a live human (as opposed to a spoof such as a photo, screen, or mask).

This endpoint creates a short-lived link for performing a face liveness verification. The end user will be guided through a liveness capture flow in their browser. Once the capture is completed (or the link expires), the result can be retrieved using the GET /api/v2/liveness_check?token=... endpoint.

The resulting data will include a numeric confidence value (confidence), the applied threshold, and a boolean passed indicator (see the result endpoint for details).

Link validity

The link is valid for a configurable number of minutes (link_valid_mins, min 5 / max 30, default 10). After expiry, if no result has been produced, the check will eventually be marked expired.

Threshold

Optionally supply a custom threshold (0-99) that will be stored alongside the check and later echoed in the result. If omitted, a system default (currently 70) is applied.

Audit images

The optional audit_images parameter (0-4) controls how many additional intermediate frame images (beyond the single probe image) are retained temporarily (up to ~30 minutes) for audit / review. These images (including bounding box metadata when available) are only returned by the result endpoint when requested via audit_images > 0 during creation.

Webhooks

If a webhook_url is supplied, lifecycle events (e.g. completion / expiry) may be posted to that URL. Webhook invocations are not retried indefinitely; implement idempotency on your side.

Webhook Signature Verification

When a webhook_url is provided and an event (e.g. completion / expiry) occurs, a POST request is sent with a JSON body and a Signature HTTP header.

The Signature header is the HMAC SHA-256 hex digest of the request body, using the secret returned when the liveness check was created as the key. It is the 64-character lowercase hex digest on its own, with no sha256= prefix.

Check the signature before acting on a webhook. Compute the digest over the raw request body exactly as received, before parsing the JSON, and compare it with the header using a constant-time comparison. Reject a request with no Signature header the same way as one with a wrong signature. Do not parse the JSON and encode it again before hashing: the body escapes forward slashes (for example in user_agent), and a re-encoded body can differ in escaping, spacing or key order, which changes the digest.

$expected = hash_hmac('sha256', $rawBody, $secret);

if (! hash_equals($expected, (string) $request->header('Signature', ''))) {
    abort(401);
}

Worked example

For a liveness check with the secret 7f6a1e88-b6d2-4d8a-9f3f-5c4d2b1a0e9f, a failed check's webhook arrives like this:

POST /webhook HTTP/1.1
Host: example.com
Content-Type: application/json
Signature: baf6eb9c3419cb5814f8bb461385775e62276df9f84fbdfd37e8b86b6f27b3d4

{"token":"u2Qe8C9vYl1kP4a7bD6fT3mN9xR5sZ0q","liveness_result":{"passed":false,"error":"failed","checked_at":"2026-10-21 14:03:12"},"user_agent":"Mozilla\/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)"}

Hashing that exact body with the secret gives the value in the Signature header. You can reproduce it on the command line:

printf '%s' '{"token":"u2Qe8C9vYl1kP4a7bD6fT3mN9xR5sZ0q","liveness_result":{"passed":false,"error":"failed","checked_at":"2026-10-21 14:03:12"},"user_agent":"Mozilla\/5.0 (iPhone; CPU iPhone OS 18_0 like Mac OS X)"}' \
  | openssl dgst -sha256 -hmac '7f6a1e88-b6d2-4d8a-9f3f-5c4d2b1a0e9f'

A completed check's body also carries the captured image, and audit_images when requested, so real bodies are much longer. The method is the same.

IP Whitelisting for Webhooks

Webhooks will originate from one of the IP addresses listed in:

IP whitelisting for webhooks

Return URL Redirect & lc_token

After the user completes the liveness flow (or the flow reaches a terminal state), the browser will be redirected to your supplied return_url with an added query parameter:

?lc_token={token}

Example: https://example.com/return?lc_token=u2Qe8C9vYl1kP4a7bD6fT3mN9xR5sZ0q

IMPORTANT: Do not trust the lc_token value from the client redirect. Always treat it as untrusted input and fetch the definitive result from the API using GET /api/v2/liveness_check?token=... under your authenticated server context. This ensures the token belongs to your account and has not been tampered with.

On terminal failure states, an additional error parameter may be appended:

?lc_token={token}&error=failed or ?lc_token={token}&error=expired

If your return_url already contains query parameters, these values will be appended using & instead of ?.