Events and Callbacks

The HID Origo Event Management and Callback Registration APIs enable applications to react to events that occur in the HID Origo platform. The Event Management API is used to configure filters and read events on demand, while the Callback Registration API enables consuming events as they happen in close to real-time using webhooks. Based on your application requirements, the event management API may be used without registering for callbacks.

Events

Events are generated when resources on HID Origo change state in a way that is likely to be actionable within your application. This includes things such as:

• Users created or deleted
• Credential lifecycle management events
• Pass lifecycle management events

The list of supported Events is available in the filterSet schema definition. New event types will be made available as new functionality is introduced to the HID Origo platform.

Retrieving events associated with a specific user is now possible with the newly available feature. To access this functionality, refer to the getEvents API, which provides detailed documentation on how to retrieve and manage user-specific events, including parameters, usage examples, and response formats.

Events follow the CloudEvents specification, which simplifies integration with many other systems that already support this standard.

Filters

Filters are resources used to reference specific types events. They may be created for either a single event or groups of events. This way, you can choose the specific event(s) your application may be interested in and optionally create separate Filters to support different use cases. Filters are also used when registering a callback subscription.

Callback Registrations

The Callback Registration API provides the option to subscribe to events by creating a callback resource. This instructs HID Origo to notify a web service of your choice whenever specific events occurs. The type of event to register is defined by referencing a Filter when the callback registration is created.

The web service you configure must meet certain criteria to receive callback events:

• Accept HTTP POST requests with body of Content-Type: application/cloudevents-batch+json
• Respond with HTTP 200 OK
• Optionally support authentication using a HTTP header

Authentication can be configured by including the httpHeader and secret parameters when creating or updating a callback resource. If provided, HID Origo will include these values in a HTTP header when calling your service. If either httpHeader or secret is supplied, the other parameter must be supplied as well. For example:

{
  "url": "https://some.web.service/callback",
  "filterId": "634988c9-8032-41d1-921f-af4f768ec1af",
  "httpHeader": "Authorization",
  "secret": "Basic Y2FsbGJhY2s6bUcyTmE2cHg2Ug=="
}

{
  "url": "https://some.web.service/callback",
  "filterId": "634988c9-8032-41d1-921f-af4f768ec1af",
  "httpHeader": "X-API-Key",
  "secret": "wg60PPe80z3Szoxv"
}

{
  "url": "https://some.web.service/callback",
  "filterId": "634988c9-8032-41d1-921f-af4f768ec1af"
}

The httpHeader and secret properties are not returned in responses when retrieving the details of callback resources.

HID Origo has a mechanism for delivering events to specified web services through callback registrations. However, it does not interpret or process the response body returned by these web services. Instead, HID Origo focuses on the delivery status of each event. If an event cannot be delivered successfully, it is marked as failed, ensuring that no event data is lost. You can retrieve these failed events via the Event Management API, which provides a way to extract undelivered event data for further handling or analysis.

If three consecutive attempts to deliver events to a registered callback url fail, the callback registration will be marked as suspended. This suspension is a temporary state in which HID Origo stops trying to deliver events to the web service. During this time, any new events that would normally be sent to the web service are also marked as failed without further delivery attempts.

HID Origo will then periodically check the availability of the suspended web service. Once the service is reachable again, the platform will resume sending events to it. This automatic resumption helps to ensure continuous event delivery while minimizing unnecessary attempts to reach an unavailable service.

Callback registrations now incorporate a defined life cycle, enabling better control over their management. This structured approach allows us to oversee the entire process—from the initial registration and activation to the eventual deactivation and removal of callbacks. As a result, we can ensure that callbacks are utilized effectively, minimizing the risk of errors and improving overall system performance.

Event Management API

The Event Management API allows querying Event history based on Filters and time period.

Callback Registration API

Provides the ability to register and manage webhooks to which HID Origo can send events. Uses filter resources configured in the Event Management API to select which callback event(s) to deliver.