FACEIO Webhooks API Reference

Receive HTTPS POST notifications when users enroll, authenticate with FACEIO, or delete a Facial ID. Use webhooks to keep your backend synchronized with facial authentication events without depending on frontend-only state.

OPEN FACEIO Console

Create or select an application in the FACEIO Console, then register your HTTPS endpoint and retrieve its webhook token from the Application Manager.

FACEIO Webhook Overview

Server-side event delivery for FACEIO enrollment, authentication, and Facial ID deletion

FACEIO webhooks notify your backend after a new face enrollment, successful facial authentication, or Facial ID deletion. Use these server-side events to reconcile your own account records with FACEIO activity.

When an event is triggered, FACEIO sends an HTTPS POST request to the webhook endpoint URL configured for your application. The JSON payload identifies the Unique Facial ID, application public ID, event name, client IP address, timestamp, linked payload when available, and enrollment details such as age approximation and gender.

Use webhook events to update backend records, write an audit trail, or trigger your own server-side workflow. Validate every incoming webhook before processing its payload, and follow the FACEIO security best practices.

Real-Time Updates

Receive event notifications when users enroll, authenticate, or complete a Facial ID deletion.

Backend Synchronization

Update internal account records from trusted server-side events instead of relying only on browser callbacks.

Configure FACEIO Webhooks

Configure a webhook endpoint for each FACEIO application that needs backend event delivery. Your endpoint should accept JSON over HTTPS, validate the WWW-Authenticate token, and return a successful response quickly.

Open the FACEIO Console

Open Application Manager

From the console main view, open the Application Manager ↗.

Select the Target Application

Choose the FACEIO application that should send enrollment, authentication, and Facial ID deletion notifications.

Open the Webhooks Tab

Navigate to the WEBHOOKS tab from the application manager view.

Add the Endpoint URL

Enter the webhook endpoint URL that will receive FACEIO events, then save the application settings.

✓

Start Receiving Events

After an event is triggered, FACEIO will make an HTTPS POST request to the webhook URL with the JSON payload described below.

HTTP Request Details

Your webhook endpoint URL must handle the incoming HTTPS request initiated by FACEIO whenever an event is triggered. The request format is summarized below.

HTTP Method	POST
Content-Type	`application/json`
POST Payload	JSON Object. Refer to the section below for the expected body fields.
Timeout	6 Seconds Your HTTP server must accept the incoming POST request in less than 6 seconds. After this delay, FACEIO automatically aborts the connection.
WWW-Authenticate Header The `WWW-Authenticate` HTTP header is always included with each POST request initiated by FACEIO.	Specific to each FACEIO application *Verify the authenticity of the request by inspecting the Bearer* token value embedded in the `WWW-Authenticate` HTTP header. It must match the token key assigned to your application.** Retrieve this token key from the Application Manager on the FACEIO Console ↗.

Security Best Practice

Always verify incoming webhook requests by comparing the WWW-Authenticate header token with your application's token key. Reject mismatches, process events idempotently, and review the security best practices before using webhook events in production authorization flows.

POST Request Body

The body of each incoming FACEIO webhook request is a JSON Object. Use the fields below to identify the event, match it to your FACEIO application, and reconcile it with your own account records.

webhook-payload.json

{
  "eventName": "String - Event Name",
  "facialId": "String - Unique Facial ID of the Target User",
  "appId": "String - Application Public ID",
  "clientIp": "String - Public IP Address",
  "payload": "Blob   - Data you have already linked to this particular user if any (Available only on the Business Plan and up)",
  "details": {
    "timestamp": "Optional String - Event Timestamp",
    "gender": "Optional String - Gender of the Enrolled User",
    "age": "Optional String - Age of the Enrolled User"
  }
}

Use the accompanying WWW-Authenticate HTTP header token value, available from the FACEIO Console ↗, to verify the authenticity of the request.

`eventName`	is the event name that triggered this particular request.
`facialId`	is the Unique Facial ID of the user being enrolled or authenticated
`appId`	is the Public ID of the application that triggered this particular request. You can find each application's Public ID on the FACEIO Console ↗.
`clientIp`	is the public IP address of the browser session that initialized `fio.js`. Review the privacy best practices before storing or retaining client IP data.
`payload`	is the data you have already associated with this particular user, if any, during enrollment. Keep payload values minimal and avoid storing secrets or unnecessary personal data. The same data will also be forwarded back to your JavaScript frontend on future authentication of the same user. The `payload` field is included in the webhook call only if your application is on the Business Plan or up. Refer to the pricing page for additional information. Under the Facial ID `DELETION` event, this field is not included in the webhook call.

Optional Fields (Enrollment Only)

The following fields from the JSON body are included for new user enrollment events:

`timestamp`	is the operation date (UTC) in the YYYY-MM-DD format.
`gender`	Gender of the enrolled user: male or female.
`age`	Age approximation of the enrolled user.

Events

Each HTTPS POST request sent to your webhook endpoint is triggered by one of the following FACEIO events. The eventName field in the JSON POST payload contains the associated key.

Event Name	Description
`ENROLL`	Fired after successful user enrollment.
`AUTH`	Fired after successful user authentication.
`DELETION`	Fired after successful Facial ID deletion.

Implementation Tips

Ensure your webhook endpoint responds within 6 seconds to avoid timeout.
Always validate the WWW-Authenticate header token for security.
Handle webhook events asynchronously and idempotently to avoid blocking your application.
Log only the metadata you need for debugging, reconciliation, and audit purposes.
Return a 200 OK status code to acknowledge receipt of the webhook.
Use the REST API when your backend needs to verify or reconcile Facial ID state after an event.

Configure Webhooks for Your Backend

Register an HTTPS webhook URL in the Console, validate the webhook token on your server, and process enrollment, authentication, and Facial ID deletion events in your backend.

Read Integration Guide → Open FACEIO Console

HTTPS Callback URL

Webhook Token Validation

Event-Driven Backend Sync