Webhooks

You can set up FindFace Security to automatically send notifications about certain events to a given URL. To do so, create and configure a webhook. In this case, when such an event occurs, FindFace Security will send an HTTP request to the URL configured for the webhook.

You can use webhooks for various purposes, for example, to notify a user about a certain event, invoke required behaviour on a target website, solve security tasks such as automated access control, etc.

In this section:

Configure Webhook

Important

You need Administrator privileges to create a webhook.

Note

To use the webhooks, be sure that at least one of the following parameters is specified in /etc/ffsecurity/config.py: SERVICE_EXTERNAL_ADDRESS or EXTERNAL_ADDRESS.

To create and configure a webhook, do the following:

1. Navigate to the Preferences tab. Click Webhooks.

2. Click +.

   

3. Specify the webhook title.

   

4. Specify URL to automatically send notifications to.

5. FindFace Security will be automatically sending notifications on events which match given filters. You can filter events by the following event parameters:

   • camera_group_in: camera group id, number.
   • matched_dossier_in: matched dossier id, number.
   • matched: event matched status (true or false), boolean.
   • camera_in: camera id, number.

   Important

   Use only filters which match your search needs. To turn off a filter, remove it from a webhook. Do not leave a filter empty ([]) as in this case the result of filtration will be empty as well.

   Note

   To get notifications about all matched events, pass only curly braces without any enclosed filters:

   {}
   

   Note

   You can specify several values for each filter (except matched). In this case, the web hook will be triggered once one of the values from this filter has been matched. In the example below, you will get an event from the camera group 1 or 3 if a matched dossier is 12 or 25.

   {
     "camera_group_in": [1, 3],
     "matched_dossier_in": [12,25]
   }
   

6. Check Active.

7. Click Save.

Webhook in Action

Try out a webhook by capturing event notifications with a simple web server in Python:

from pprint import pprint
from aiohttp import web


async def handle(request):
    pprint(await request.json())
    return web.Response(status=200)


app = web.Application()
# for aiohttp v 3.x
# app.add_routes([web.post('/', handle)])

# for aiohttp v 2.x
app.router.add_post('/', handle)

web.run_app(app, port=8888)

If no filters are configured for a webhook, this web server will be getting notifications about each event that occurs in the system. The notifications have the following format:

======== Running on http://0.0.0.0:8888 ========
(Press CTRL+C to quit)
[{'acknowledged': True,
  'acknowledged_by': None,
  'acknowledged_date': '2019-04-09T12:29:23Z',
  'acknowledged_reaction': None,
  'camera': 2,
  'confidence': 0.9098,
  'created_date': '2019-04-09T12:29:23Z',
  'face': 'http://172.20.77.17/uploads/2019/04/09/event/122955_face_aT3ZZh.jpg',
  'features': {'age': None,
               'beard': None,
               'emotions': None,
               'gender': None,
               'glasses': None,
               'liveness': None},
  'frame': 'http://172.20.77.17/uploads/2019/04/09/event/122955_image_3msdHH.jpg',
  'frame_coords_bottom': 981,
  'frame_coords_left': 1630,
  'frame_coords_right': 1911,
  'frame_coords_top': 701,
  'id': '4173669353687265180',
  'looks_like_confidence': None,
  'matched': True,
  'matched_dossier': 1,
  'matched_face': '4173665826982243136',
  'matched_lists': [1],
  'normalized_photo': 'http://172.20.77.17/uploads/2019/04/09/event/122955_face0_E638aW.png',
  'quality': -0.000158,
  'scores': {'direction_score': -2.62964,
             'frame_no': 800,
             'score': -0.000158435,
            'tracking_duration': 34000}}]

To view the webhook pulling status, execute:

sudo journalctl -u  findface-security.service | grep webhook

Success:

`Apr 09 16:02:28 ubuntu ffsecurity[1524]: INFO     [-] hook 1 was pulled on http://172.20.77.70:8888`

Failure:

`Apr 09 15:59:02 ubuntu ffsecurity[1524]: INFO     [-] While working on hook 1 Exception occured: Cannot connect to host 172.20.77.70:8888 ssl:False [Connection refused]`