What are Webhooks?
Webhooks allows you to receive data and get notified at real-time about the ongoing events during the interaction of the FACEIO Widget with your users (eg. New facial enrollment or authentication) in-order to keep your application backend up-to-date & synchronized. FACEIO uses Webhooks to let your system know when such events happen. Events includes New User Enrollment, Facial Authentication Success, Facial ID Deletion and many other events.
When an event occurs, FACEIO makes an HTTP POST request to the URL you configured for the Webhook. FACEIO’s request includes details of the ongoing event such as the Unique Facial ID of the user being enrolled or authenticated, its gender & age in case of new enrollment, timestamps, event type, IP information, linked payload, and many others details.
Setting up Webhooks
Setting up Webhooks for your application is straightforward. Follow the steps below to register your first webhook endpoint URL:
- Connect to your account via the FACEIO Console first.
- From the console main view, visit the Application Manager .
- Select the target application for which you want to setup webhooks for.
- Navigate to the WEBHOOKS tab from the manager main view.
- Once the target application selected. Enter your Webhook Endpoint URL for receiving events and save your modification.
- You're all set. Upon an event is triggered, FACEIO shall make an HTTP POST request to the URL you configured for the Webhook with the below details.
HTTP Request Details
Your Webhook Endpoint URL, must be able to handle the incoming HTTP request initiated by FACEIO whenever an event is triggered. Below, details of the incoming HTTP Request:
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 be able to accept the incoming POST request in less than 6 seconds. Passing this delay, FACEIO shall automatically abort the connection. |
WWW-Authenticate Header The |
Specific to each application
You can verify the authenticity of the request by inspecting the Bearer token value embedded in the |
Post Request Body
Below, the body of the incoming HTTP POST request initiated by FACEIO. The body is a JSON Object
with the following fields:
{ "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" } }
You can rely on the accompanying WWW-Authenticate
HTTP header token value (found on 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 all your applications Public IDs on the FACEIO Console. |
clientIp |
is the public IP address that triggered fio.js instantiation on the browser side. |
payload |
is the data you have already associated to this particular user (if any) during his enrollment. The same data will also be forwarded back to your JS frontend on future authentication of the same user. The payload field is included within the Webhook call only if your application is on the Business Plan or up. Refer to our Pricing Page for additional information. Please note that under the Facial ID DELETION event, this field will not be included at all within the Webhook call. |
Optionally, the following object fields from the already sent JSON body
are always included in case of new user enrollment.
Optional key/value pairs included only during enrollment:
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 HTTP POST request made to the URL you specified for the Webhook, is triggered by one of the following events. The eventName
of the JSON POST Payload is 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. |