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 +.

    create_webhook_en

  3. Specify the webhook title.

    webhook_en

  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)

Important

A webhook catcher that you use must return an HTTP 200 response after receiving the webhook request from FindFace Security, like in the example above.

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 'WebhookUpdaterService'

Success:

Jan 24 14:08:49 ffsec4 ffsecurity[25316]: INFO     [WebhookUpdaterService] [SC:PcQr6bjA-VW:bea6c7b5] Webhook updater got event 4240944471810639375
Jan 24 14:08:49 ffsec4 ffsecurity[25316]: INFO     [WebhookUpdaterService] [SC:PcQr6bjA-VW:bea6c7b5] Event 4240944471810639375 enqueued for webhook 1 (1 items in queue)
Jan 24 14:08:49 ffsec4 ffsecurity[25316]: INFO     [WebhookUpdaterService:1] <queue:  0> Received 1 events from queue: ['4240944471810639375']
Jan 24 14:08:50 ffsec4 ffsecurity[25316]: INFO     [WebhookUpdaterService:1] <queue:  0> Attempting to send 1 events
Jan 24 14:08:50 ffsec4 ffsecurity[25316]: INFO     [WebhookUpdaterService:1] <queue:  0> Sent 1 events: ['4240944471810639375']

Failure:

Jan 24 14:09:02 ffsec4 ffsecurity[25316]: INFO     [WebhookUpdaterService] [SC:TSlJfHlU-VW:107b37da] Webhook updater got event 4240944506705010458
Jan 24 14:09:02 ffsec4 ffsecurity[25316]: INFO     [WebhookUpdaterService] [SC:TSlJfHlU-VW:107b37da] Event 4240944506705010458 enqueued for webhook 1 (1 items in queue)
Jan 24 14:09:02 ffsec4 ffsecurity[25316]: INFO     [WebhookUpdaterService:1] <queue:  0> Received 1 events from queue: ['4240944506705010458']
Jan 24 14:09:02 ffsec4 ffsecurity[25316]: WARNING  [WebhookUpdaterService:1] <queue:  0> Backing off for 0.270 seconds after failure: ClientConnectorError(111, 'Connection refused')
Jan 24 14:09:03 ffsec4 ffsecurity[25316]: WARNING  [WebhookUpdaterService:1] <queue:  0> Backing off for 0.729 seconds after failure: ClientConnectorError(111, 'Connection refused')
Jan 24 14:09:03 ffsec4 ffsecurity[25316]: WARNING  [WebhookUpdaterService:1] <queue:  0> Backing off for 1.968 seconds after failure: ClientConnectorError(111, 'Connection refused')