Skip to main content

LPR WebHook

In this guide, you will learn how to set up your web server to receive HTTP postbacks from Events Bridge when a license plate detection event occurs. The system will post event data to your web server, following the WebHookLprPayload model.

Your web server must be configured to handle incoming HTTP POST requests, and optionally validate authentication based on the configuration set in Events Bridge.

To have these events delivered at all, a WebHook must be registered with webHookLpr 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. An LPR event carries several base64-encoded crops, so its payload is typically larger than a face event.
  • 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 how Events Bridge is configured.

Authentication (Optional)​

Events Bridge can be configured to send authentication information with each POST request, using either:

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

Your web server must be able to validate these headers to accept the request.

HTTPS Encouraged​

Using HTTPS is recommended for security, but Events Bridge can be configured to accept self-signed certificates if needed. This allows you to secure communication even if using self-signed SSL certificates.

WebHook Payload: WebHookLprPayload​

When Events Bridge detects a license plate, it sends 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/lpr, which needs no authentication and is useful for generating types or seeding test fixtures.

Full Example Payload​

{
  "publishType": "WebHookLprPayload",
  "sourceName": "eConnect Site 1 LPR",
  "externalId": "98765",
  "fields": [
    {
      "fieldName": "TenantID",
      "fieldValue": "ABC123"
    }
  ],
  "serverContext": {
    "SiteId": "54321",
    "PropertyName": "Parking Facility A",
    "Region": "East Coast"
  },
  "payload": {
    "lprPlateInfo": {
      "plate": "XYZ987",
      "similar1Plate": "XYZ987",
      "vehicleMake": "Toyota",
      "vehicleModel": "Camry",
      "vehicleColor": "Blue",
      "vehicleState": "CA",
      "tags": [
        {
          "tagName": "VIP",
          "expires": "2024-12-31T23:59:59Z"
        }
      ],
      "fields": [
        {
          "fieldName": "DriverLicenseNumber",
          "stringValue": "D1234567",
          "dateValue": null,
          "numberValue": null,
          "boolValue": null
        }
      ]
    },
    "detectionInfo": {
      "dateTimeUtc": "2024-10-22T10:00:00Z",
      "timeZone": "America/Los_Angeles",
      "detectorName": "EntranceCamera1"
    },
    "detectionImages": [
      {
        "image": "base64_encoded_image_data",
        "cropSizeName": "Close"
      },
      {
        "image": "base64_encoded_image_data",
        "cropSizeName": "Car"
      }
    ],
    "detectionHistory": {
      "visitHistory": [
        {
          "dateTimeUtc": "2024-10-20T09:00:00Z",
          "detectorName": "EntranceCamera2"
        }
      ]
    },
    "resentEvent": false,
    "messageId": "2b7e4c19-8a63-4f05-b1de-6c3a9d240f57"
  }
}

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: "WebHookLprPayload"

1. sourceName (String)​

  • Description: The name of the site location where the license plate was detected. This is useful in multi-site setups to identify the location of the detection.
  • Example: "ParkingLot1"

2. externalId (String, Optional)​

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

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: "ABC123"
Two different field shapes

This top-level fields array uses fieldValue. The fields array nested inside lprPlateInfo 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": "54321",
      "PropertyName": "Parking Facility A",
      "Region": "East 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 vehicle and the detection event.

5.1 lprPlateInfo (Object)​

  • Description: Information about the detected vehicle, including its license plate, make, model, and any associated tags or custom fields.
Sub-fields:​
  • plate (String): The license plate number as read by the detector.
    • Example: "XYZ987"
  • similar1Plate (String, Optional): A normalized form of the plate used for fuzzy matching, produced by folding characters that OCR commonly confuses. Match on this value when you need to tolerate misreads. The normalization rules are internal — treat the value as opaque and compare against it rather than deriving it yourself. It is identical to plate when the plate contains nothing ambiguous.
    • Example: "XYZ987"
  • vehicleMake (String, Optional): The make of the vehicle (if available).
    • Example: "Toyota"
  • vehicleModel (String, Optional): The model of the vehicle (if available).
    • Example: "Camry"
  • vehicleColor (String, Optional): The color of the vehicle (if available).
    • Example: "Blue"
  • vehicleState (String, Optional): The state or region where the vehicle is registered (if available).
    • Example: "CA"
  • tags (Array of Objects, Optional): Tags associated with the vehicle, categorizing it (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): 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 associated with the vehicle. 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: "DriverLicenseNumber"
    • stringValue (String, Optional): The value when the field holds text.
      • Example: "D1234567"
    • 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.

5.2 detectionInfo (Object)​

  • Description: Information about the detection event, including the time and location of the detection.
Sub-fields:​
  • dateTimeUtc (String): The date and time of the detection, in UTC (ISO 8601 format).
    • Example: "2024-10-22T10:00:00Z"
  • timeZone (String, Optional): The IANA time zone where the detection occurred. Use this to render dateTimeUtc in local time.
    • Example: "America/Los_Angeles"
  • detectorName (String): The name of the camera or detector that captured the license plate.
    • Example: "EntranceCamera1"
No confidence score on LPR events

Unlike a face detection, an LPR event carries no confidence field. Use similar1Plate if you need to reason about uncertain reads.

5.3 detectionImages (Array of Objects, Optional)​

  • Description: The images captured at the time of the detection. Several crops of the same moment are usually supplied, from a tight shot of the plate to the whole frame.
Sub-fields:​
  • image (String): The image of the vehicle or license plate, encoded in base64.
    • Example: "base64_encoded_image_data"
  • cropSizeName (String): Which crop this image is — "Close", "Medium", "Car", "FullFrame" or "Other". Select by name rather than by array position.
    • Example: "Close"

5.4 detectionHistory (Object, Optional)​

  • Description: Contains information about past visits or interactions with the vehicle.
Sub-fields:​
  • visitHistory (Array of Objects, Optional): A list of previous detections of the vehicle.
    • dateTimeUtc (String): The date and time of the previous detection (ISO 8601 format).
      • Example: "2024-10-20T09:00:00Z"
    • detectorName (String): The name of the detector that captured the previous detection.
      • Example: "EntranceCamera2"

5.5 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.6 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: "2b7e4c19-8a63-4f05-b1de-6c3a9d240f57"

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