Webhooks

Webhook is a user-defined HTTP callbacks, triggering by an event in a web app.

You can use webhooks for various purposes, for instance, to notify a user about a specific Event, invoke required behavior on a target website, and solve security tasks such as automated access control.

For example, if you set up an edge device and want to send the result of recognition back to proceed with the object verification.

In order to FindFace Lite send an HTTP request to the URL when a required event occurs, configure the webhook.

Authenticate a device

To authenticate your device in the system, use /v1/auth/login POST request.

For username and password parameters use data you got on the STEP 5.

Request example:

{
  "username": "login",
  "password": "password"
}

Successfull response example:

{
  "access_token": "token"
}

Create a Webhook

To create a webhook use /v1/webhooks/ POST request. Below are described all parameters and values type:

Parameters	Value types	Description
name	string	The name of a webhook.
active	true	The default value, which means that the webhook is enabled.
active	false	The possible value, which means that the webhook is disabled.
target	string	Target URL to call when an event happens.
filters	object [filters]	A set of filters, according to which messages are sent or not to the target URL. Only specified filters influence the Webhook work. If empty, all Events are sent to the target URL.
type_in	string	If the created Event is matched with the specified types (face, car or license_plate), a message is sent to the target URL.
camera_in	a number or several numbers	If the created Event is connected with the specified Camera ID, a message is sent to the target URL.
card_in	a number or several numbers	If the created Event is matched with the specified Card ID, a message is sent to the target URL.
confidence_gte	a number from 0 to 1	If the result of recognition is greater than or equal to the specified value, a message is sent to the target URL.
confidence_lte	a number from 0 to 1	If the result of recognition is less than or equal to the specified value, a message is sent to the target URL.
matched	true	Only matched Events will trigger a message sending to the target URL.
matched	false	Only unmatched Events will trigger a message sending to the target URL.
bs_type_in	overall	Only the best result of recognition for a particular time will trigger a message sending to the target URL.
bs_type_in	realtime	All results of recognition will trigger a message sending to the target URL.
Yaw, Pitch, Roll		Parameters mean the angle of rotation in grades. They can only be apply if in the configuration file there is a headpose value for the face_features.
yaw_lte	a number	If the headpose yaw is less than or equal to the specified value, a message is sent to the target URL.
yaw_gte	a number	If the headpose yaw is greater than or equal to the specified value, a message is sent to the target URL.
pitch_lte	a number	If the headpose pitch is less than or equal to the specified value, a message is sent to the target URL.
pitch_gte	a number	If the headpose pitch is greater than or equal to the specified value, a message is sent to the target URL.
roll_lte	a number	If the headpose roll is less than or equal to the specified value, a message is sent to the target URL.
roll_gte	a number	If the headpose roll is greater than or equal to the specified value, a message is sent to the target URL.

liveness_lte	a number from 0 to 1	If the liveness level is less than or equal to the specified value, a message is sent to the target URL.
liveness_gte	a number from 0 to 1	If the liveness level is greater than or equal to the specified value, a message is sent to the target URL.

medmask	object	If the medmask feature is specified in the confinguration file, you can filter messages, sent to the target URL, by the result of medmask analysis while face recognition.
name	enum	Available opttons according to which events can be filtered:
		none – there is no medmask on the face;
		correct – medmask is put on correctly;
		incorrect – medmask is put on incorrectly.
confidence_lte	a number from 0 to 1	If the confidence value of medmask recognition result is less than or equal to the specified value, a message is sent to the target URL.
confidence_gte	a number from 0 to 1	If the confidence value of medmask recognition result is greater than or equal to the specified value, a message is sent to the target URL.
orientation	object	If the orientation feature is specified in the confinguration file, you can filter webhooks by the result of car orientation analysis while car recognition.
name	enum	Available event recognition results according to which they can be filtered:
		back – vehicle rear part;
		side – vehicle side part;
		front – vehicle front part.
confidence_lte	a number from 0 to 1	If the confidence value of car orientation recognition result is less than or equal to the specified value, a message is sent to the target URL.
confidence_gte	a number from 0 to 1	If the confidence value of car orientation recognition result is less than or equal to the specified value, a message is sent to the target URL.
special_type	object	If the special_type feature is specified in the confinguration file, you can filter webhooks by the result of car type analysis while car recognition.
name	enum	Available event recognition results according to which they can be filtered:
		not_special – ordinary vehicle,
		police,
		ambulance,
		road_service,
		gas_service,
		rescue_service,
		other_special – all other special vehicles that are not specified as a separated group,
		taxi,
		route_transport,
		car_sharing,
		military.
confidence_lte	a number from 0 to 1	If the confidence value of car type recognition result is less than or equal to the specified value, a message is sent to the target URL.
confidence_gte	a number from 0 to 1	If the confidence value of car type recognition result is greater than or equal to the specified value, a message is sent to the target URL.
license_plate_number	string	If the recognised car license plate number is equal to the specified value, a message is sent to the target URL.
license_plate_visibility	object	license_plate_visibility is mandatory feature and enabled implicitly in the configuration file. You can filter webhooks by the result of car license plate visibility while car recognition.
name	enum	Available event recognition results according to which they can be filtered:
		partly_visible_no_text – license plate is without text and partly visible,
		fully_visible_no_text – license plate is without text and fully visible,
		invisible – license plate is invisible,
		partly_visible – license plate is with text and partly visible,
		fully_visible – license plate is with text and fully visible.
confidence_lte	a number from 0 to 1	If the confidence value of car orientation recognition result is less than or equal to the specified value, a message is sent to the target URL.
confidence_gte	a number from 0 to 1	If the confidence value of car orientation recognition result is less than or equal to the specified value, a message is sent to the target URL.
license_plate_event_number	string	Filter can only be applied to license_plate Event type. If the recognised car license plate number in the event is equal to the specified value, a message is sent to the target URL.
send_attempts	a number	Numbers of attempts to send a message to the target URL. The attempts are unlimited if 0 is set.

Request example:

{
  "name": "test webhook",
  "active": true,
  "target": "http://localhost/webhok_test",
  "filters": {
    "camera_in": [
      1,
      2
    ],
    "card_in": [
      4,
      5
    ],
    "confidence_gte": 0.75,
    "confidence_lte": 0.79,
    "matched": true,
    "bs_type_in": [
      "overall",
      "realtime"
    ],
    "yaw_lte": 3.5,
    "yaw_gte": 3.5,
    "pitch_lte": -4.2,
    "pitch_gte": -4.2,
    "roll_lte": 1.8,
    "roll_gte": 1.8,
    "liveness_lte": 0.44,
    "liveness_gte": 0.44
  },
  "send_attempts": 3
}

Successfull response example:

{
  "name": "test webhook",
  "active": true,
  "target": "http://localhost/webhok_test",
  "filters": {
    "camera_in": [
      1,
      2
    ],
    "card_in": [
      4,
      5
    ],
    "confidence_gte": 0.75,
    "confidence_lte": 0.79,
    "matched": true,
    "bs_type_in": [
      "overall",
      "realtime"
    ],
    "yaw_lte": 3.5,
    "yaw_gte": 3.5,
    "pitch_lte": -4.2,
    "pitch_gte": -4.2,
    "roll_lte": 1.8,
    "roll_gte": 1.8,
    "liveness_lte": 0.44,
    "liveness_gte": 0.44
  },
  "send_attempts": 3,
  "id": 1
}