Skip to main content

Face WebHook

In this guide, you will learn how to set up your web server to receive HTTP postbacks from Events Bridge. When a face detection event occurs, Events Bridge will post the event data to your web server. This event data follows the WebHookFaceRecPayload model.

Your web server needs to be configured to handle incoming HTTP POST requests and optionally authenticate the request based on the configuration set in Events Bridge.

Requirements​

Web Server Setup​

Your web server must:

  • Accept HTTP POST requests at a publicly or privately accessible URL.
  • Be configured to parse JSON data from incoming requests.
  • Optionally support authentication methods like Basic Authentication or Bearer Tokens, depending on the settings configured in Events Bridge.

Authentication (Optional)​

Events Bridge can be configured to send authentication information with each POST request. This can be done using:

  • Basic Authentication: The server will include a username and password in the request headers.
  • Bearer Token: The server will include a bearer token in the request headers under Authorization.

Your web server should validate these headers before processing the payload.

HTTPS Encouraged​

We encourage using HTTPS for security, but Events Bridge can be configured to accept self-signed certificates if needed. This configuration ensures that you can still secure your connection even if your server uses a self-signed SSL certificate.

WebHook Payload: WebHookFaceRecPayload​

When Events Bridge detects a face, it will send a POST request to your web server with the following payload structure:

Full Example Payload​

{
  "publishType": "WebHookFaceRecPayload",
  "sourceName": "eConnect Site 1 FR",
  "externalId": "12345",
  "fields": [
    {
      "fieldName": "TenantID",
      "fieldValue": "XYZ987"
    }
  ],
  "payload": {
    "personInfo": {
      "faceId": "abc12345",
      "firstName": "John",
      "middleName": "Michael",
      "lastName": "Doe",
      "tags": [
        {
          "tagName": "VIP",
          "expires": "2024-12-31T23:59:59Z"
        }
      ],
      "fields": [
        {
          "fieldName": "DateOfBirth",
          "stringValue": "1980-05-01",
          "dateValue": null,
          "numberValue": null,
          "boolValue": null
        }
      ],
      "notes": [
        {
          "noteTitle": "string",
          "noteBody": "string"
        }
      ]
    },
    "detectionInfo": {
      "dateTimeUtc": "2024-10-22T10:00:00Z",
      "confidence": 98.7,
      "detectorName": "EntranceCamera1",
      "detectId": "det12345",
      "timeZone": "America/Los_Angeles"
    },
    "detectionImage":{
        "image": "base64_encoded_image_data",
    },
    "defaultPhoto": {
      "image": "base64_encoded_image_data",
    },
    "detectionHistory": {
      "visitHistory": [
        {
          "dateTimeUtc": "2024-10-20T09:00:00Z",
          "detectorName": "EntranceCamera2"
        }
      ],
      "printHistory": [
        {
          "dateTimeUtc": "2024-10-20T09:05:00Z",
          "printerName": "IDCardPrinter1"
        }
      ]
    },
    "resentEvent": false
  }
}

Field Descriptions​

publishType (string)​

  • Description: The type discriminator of the object, used as a helper for deserialization.
  • Example: "WebHookFaceRecPayload"

1. sourceName (String)​

  • Description: The name of the site location where the detection originated. Useful for identifying the location of the event, especially in multi-site setups.
  • Example: "LasVegasCasino1"

2. externalId (String)​

  • Description: A unique identifier provided by the partner’s system during the enrollment process. This allows partners to associate detections with their internal records.
  • Example: "12345"

3. fields (Array of Objects)​

  • Description: An array of custom fields passed during enrollment. These fields contain additional data relevant to the enrolled person or the detection.
  • Sub-fields:
    • fieldName (String): The name of the custom field.
      • Example: "TenantID"
    • stringValue (String): The value assigned to the field.
      • Example: "XYZ987"

4. payload (Object)​

  • Description: Contains detailed information about the detected individual and the detection event.

4.1 personInfo (Object)​

  • Description: Information about the detected individual, including their unique face ID, personal details, tags, and any custom fields.
Sub-fields:​
  • faceId (String): A unique identifier for the detected face in the Events Bridge system.
    • Example: "abc12345"
  • firstName (String, Optional): The individual's first name, if available.
    • Example: "John"
  • middleName (String, Optional): The individual's middle name, if available.
    • Example: "Michael"
  • lastName (String, Optional): The individual's last name, if available.
    • Example: "Doe"
  • tags (Array of Objects, Optional): Tags associated with the person, which categorize the individual (e.g., "VIP", "Banned").
    • tagName (String): The name of the tag.
      • Example: "VIP"
    • expires (String, Optional): The expiration date of the tag, in ISO 8601 format.
      • Example: "2024-12-31T23:59:59Z"
  • fields (Array of Objects, Optional): Custom fields containing additional information about the individual.
    • fieldName (String): The name of the field.
      • Example: "DateOfBirth"
    • fieldValue (String): The value assigned to the field.
      • Example: "1980-05-01"

4.2 detectionInfo (Object)​

  • Description: Contains details about the detection event, such as when and where the detection occurred, and the confidence score of the facial match.
Sub-fields:​
  • dateTimeUtc (String): The UTC date and time when the detection occurred, in ISO 8601 format.
    • Example: "2024-10-22T10:00:00Z"
  • confidence (Number): The confidence level of the face match, represented as a percentage.
    • Example: 98.7
  • detectorName (String): The name of the camera or detector that captured the face.
    • Example: "EntranceCamera1"
  • detectId (String): A unique identifier for the detection event.
    • Example: "det12345"
  • timeZone (String, Optional): The time zone in which the detection occurred. IANA
    • Example: "America/Los_Angeles"

4.3 defaultPhoto (Object, Optional)​

  • Description: Contains a base64-encoded image of the detected individual, typically captured at the time of detection.
Sub-fields:​
  • image (String): A base64-encoded image of the detected individual.
    • Example: "base64_encoded_image_data"
  • cropSizeName (String): The size of the image crop, such as "Full" or "Thumbnail."
    • Example: "Full"

4.4 detectionHistory (Object, Optional)​

  • Description: Contains historical information about the detected individual’s prior visits and interactions with the system.
Sub-fields:​

  • visitHistory (Array of Objects, Optional): A list of past detections of the individual.

    • dateTimeUtc (String): The UTC date and time of the past detection.
      • Example: "2024-10-20T09:00:00Z"
    • detectorName (String): The name of the detector that captured the previous detection.
      • Example: "EntranceCamera2"

  • printHistory (Array of Objects, Optional): A list of past prints or interactions with physical devices related to the individual (e.g., ID card printing).

    • dateTimeUtc (String): The UTC date and time when the interaction occurred.
      • Example: "2024-10-20T09:05:00Z"
    • printerName (String): The name of the printer or device involved in the interaction.
      • Example: "IDCardPrinter1"

Authentication Handling​

If Events Bridge is configured to use Basic Authentication or Bearer Token, your web server will need to validate the incoming request headers.

Basic Authentication​

With Basic Authentication, the Authorization header will contain a base64-encoded username and password. Your web server should decode and verify these credentials.

Bearer Token​

With Bearer Token authentication, the Authorization header will contain a token. Your server should validate this token before processing the request.

Final Notes​

  • Your web server can be hosted on either a public or private network, as long as Events Bridge can access it.
  • Ensure that your web server is always available to receive POST requests from Events Bridge.
  • For security, use HTTPS for all communication, even if it’s with a self-signed certificate, which is supported by Events Bridge.