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:

  1. Connect to your account via the FACEIO Console first.
  2. From the console main view, visit the Application Manager .
  3. Select the target application for which you want to setup webhooks for.
  4. Navigate  to the WEBHOOKS tab from the manager main view.
  5. Once the target application selected. Enter your Webhook Endpoint URL for receiving events and save your modification.
  6. 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 WWW-Authenticate HTTP header is always included with each POST request initiated by FACEIO.

Specific to each application

You can verify the authenticity of the request by inspecting the Bearer token value embedded in the WWW-Authenticate HTTP header which must match the token key assigned to your application.
Retrieve this token key from the Application Manager on the FACEIO Console .

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.