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 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. On 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 any 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 payload data.
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 embedded in the WWW-Authenticate HTTP header which must match the token value assigned to your application.

Post Request Payload

Below, the payload of each incoming HTTP POST request initiated by FACEIO. The payload is a JSON Object with the following key/value pairs:

{
  "eventName":"String - Event Name",
  "facialId": "String - Unique Facial ID of the Target User",
  "appId":    "String - Application Public ID",
  "clientIp": "String - Public IP Address",
  "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 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.

Optionally, the following fields from the payload JSON object (details) 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.