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.

To have these events delivered at all, a WebHook must be registered with webHookFaceRec set to true — see Automating WebHook Setup or Manually Setting Up a WebHook.

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.
  • Accept request bodies of at least a few hundred kilobytes. The image fields are base64-encoded photographs and dominate the payload size.
  • Respond with a 2xx status code quickly. Events Bridge treats anything else as a failed delivery, and a slow response causes retries or a timeout.
  • 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.

You can fetch a live copy of this exact shape from /api/v1/webhook-models/face, which needs no authentication and is useful for generating types or seeding test fixtures.

Full Example Payload​

{
  "publishType": "WebHookFaceRecPayload",
  "sourceName": "eConnect Site 1 FR",
  "externalId": "12345",
  "fields": [
    {
      "fieldName": "TenantID",
      "fieldValue": "XYZ987"
    }
  ],
  "serverContext": {
    "SiteId": "12345",
    "PropertyName": "Downtown Casino",
    "Region": "West Coast"
  },
  "payload": {
    "personInfo": {
      "faceId": "abc12345",
      "firstName": "John",
      "lastName": "Doe",
      "middleName": "Michael",
      "tags": [
        {
          "tagName": "VIP",
          "expires": "2024-12-31T23:59:59Z"
        }
      ],
      "fields": [
        {
          "fieldName": "DateOfBirth",
          "stringValue": "1980-05-01",
          "dateValue": null,
          "numberValue": null,
          "boolValue": null
        }
      ],
      "notes": [
        {
          "noteTitle": "Monitor Reason",
          "noteBody": "Enrolled by PartnerSystem for VIP monitoring"
        }
      ]
    },
    "detectionInfo": {
      "dateTimeUtc": "2024-10-22T10:00:00Z",
      "timeZone": "America/Los_Angeles",
      "confidence": 0.987,
      "detectId": "det12345",
      "detectorName": "EntranceCamera1"
    },
    "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,
    "messageId": "9f1d6b5a-3c2e-4a71-9d88-0b4c5e6f7a81"
  }
}

Field Descriptions​

publishType (String)​

  • Description: The type discriminator of the object, used as a helper for deserialization. Route on this value if a single endpoint receives both face and plate events.
  • 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, Optional)​

  • Description: The unique identifier your system supplied when the person was enrolled, which lets you match a detection back to your own records. It is null when the detected person was not enrolled by you — which happens whenever filterRules is set to anything broader than "Expected".
  • Example: "12345"

3. fields (Array of Objects, Optional)​

  • Description: The additionalFields you supplied at enrollment, replayed back to you unchanged.
  • Sub-fields:
    • fieldName (String): The name of the custom field.
      • Example: "TenantID"
    • fieldValue (String): The value assigned to the field.
      • Example: "XYZ987"
Two different field shapes

This top-level fields array uses fieldValue. The fields array nested inside personInfo is a different type that uses stringValue, dateValue, numberValue and boolValue instead. See section 5.1.

4. serverContext (Object, Optional)​

  • Description: A dictionary of key/value pairs configured by administrators that provide context about the server or property that generated this webhook. Since Events Bridge acts as a bridge between multiple Identity Servers and Classic Servers, this context helps webhook receivers identify the origin of the detection event. Common keys include SiteId, PropertyName, Region, TenantId, or any custom identifiers.
  • Example: 
    {
      "SiteId": "12345",
      "PropertyName": "Downtown Casino",
      "Region": "West Coast"
    }
  • Use Cases:
    • Identify which property or location sent the detection
    • Route events to appropriate handlers in multi-tenant systems
    • Apply property-specific business logic
    • Maintain audit trails of event origins
  • Note: This is null when no context has been configured for the originating server. Handle both cases.

5. payload (Object)​

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

5.1 personInfo (Object)​

  • Description: Information about the detected individual, including their unique face ID, personal details, tags, custom fields and notes.
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"
  • lastName (String, Optional): The individual's last name, if available.
    • Example: "Doe"
  • middleName (String, Optional): The individual's middle name, if available.
    • Example: "Michael"
  • 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. Tags you created are prefixed with your account's field prefix, for example SystemA-Banned.
      • Example: "VIP"
    • expires (String, Optional): The expiration date of the tag, in ISO 8601 format. null means the tag does not expire.
      • Example: "2024-12-31T23:59:59Z"
  • fields (Array of Objects, Optional): Custom fields containing additional information about the individual. Each entry carries its value in exactly one of the typed value properties; the rest are null.
    • fieldName (String): The name of the field.
      • Example: "DateOfBirth"
    • stringValue (String, Optional): The value when the field holds text.
      • Example: "1980-05-01"
    • dateValue (String, Optional): The value when the field holds a date, in ISO 8601 format.
    • numberValue (Number, Optional): The value when the field holds a number.
    • boolValue (Boolean, Optional): The value when the field holds a true/false flag.
  • notes (Array of Objects, Optional): Free-text notes recorded against the individual. The monitorReason supplied at enrollment appears here.
    • noteTitle (String): The note's heading.
      • Example: "Monitor Reason"
    • noteBody (String): The note's text.

5.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"
  • timeZone (String, Optional): The IANA time zone in which the detection occurred. Use this to render dateTimeUtc in local time.
    • Example: "America/Los_Angeles"
  • confidence (Number): The confidence of the face match, as a fraction between 0 and 1 — not a percentage. Multiply by 100 to display it as one.
    • Example: 0.987 (a 98.7% match)
  • detectId (String): A unique identifier for the detection event.
    • Example: "det12345"
  • detectorName (String): The name of the camera or detector that captured the face.
    • Example: "EntranceCamera1"

5.3 detectionImage (Object, Optional)​

  • Description: The frame captured at the moment of detection — what the camera actually saw.
Sub-fields:​
  • image (String): A base64-encoded image.
    • Example: "base64_encoded_image_data"

5.4 defaultPhoto (Object, Optional)​

  • Description: The enrolled reference photograph for this individual — the image on file, not the live capture. Compare it against detectionImage to show an operator both sides of the match.
Sub-fields:​
  • image (String): A base64-encoded image.
    • Example: "base64_encoded_image_data"

5.5 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"

5.6 resentEvent (Boolean)​

  • Description: true when this delivery is a replay of an event Events Bridge has already attempted to send, for example after your endpoint was unreachable and a resilient WebHook retried. Use it together with messageId to avoid double-processing.
  • Example: false

5.7 messageId (String, Optional)​

  • Description: A unique identifier for this detection message, stable across retries. Store it and discard duplicates — this is the recommended idempotency key.
  • Example: "9f1d6b5a-3c2e-4a71-9d88-0b4c5e6f7a81"

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.
  • Deduplicate on messageId. A resilient WebHook retries until it gets a 200, so a receiver that succeeds slowly can see the same event twice.
  • Acknowledge before you process. Return 200 as soon as you have the payload safely queued; doing database or image work inline invites retries.
  • For security, use HTTPS for all communication, even if it's with a self-signed certificate, which is supported by Events Bridge.
  • Verify your receiver end-to-end with Send a Test Event before going live.
Last updated on by Travis Whidden