Webhooks ========= .. _webhook: :term:`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 :ref:`the STEP 5 `. **Request example:** .. code-block:: json { "username": "login", "password": "password" } **Successfull response example:** .. code-block:: json { "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. | | +-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | 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. | | +-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | 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. | | +-----------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+ | | 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:** .. code-block:: json { "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:** .. code-block:: json { "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 }