Skip to content

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

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.

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

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

HID Origo will not interpret or process the body of the response returned by the specified web service. Any Events that are not successfully delivered will be marked as failed and can be extracted using the Event Management API - no event data is lost. Callback registrations may be removed if the registered web service is unavailable for an extended time period.

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.