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 of 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 occur. 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 an 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 an HTTP header when calling your service. If either httpHeader or secret is supplied, the other parameter must be supplied as well. For example:

Alternatively, callbacks can be configured with OAuth 2.0 Client Credentials authentication by including the oauthCredentials object. When OAuth is configured, HID Origo automatically acquires an access token using the client_credentials grant type and delivers events with an Authorization: Bearer <access_token> header. Four authentication methods are supported per RFC 7591 / OpenID Connect: client_secret_basic, client_secret_post, client_secret_jwt, and private_key_jwt.

Basic AuthenticationAPI KeyClient Secret BasicClient Secret PostClient Secret JWTPrivate Key JWTNo Authentication

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

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

{
  "url": "https://api.partner-bank.com/callbacks/events",
  "filterId": "43958afa-057e-4db7-a765-a5757aa42ec8",
  "authType": "OAUTH",
  "durationInDays": 90,
  "status": "ACTIVE",
  "oauthCredentials": {
    "tokenEndpoint": {
      "tokenUrl": "https://auth.partner-bank.com/oauth2/token",
      "grantType": "client_credentials",
      "scope": "callbacks.write"
    },
    "clientAuthentication": {
      "authMethod": "client_secret_basic",
      "clientId": "origo-callback-client",
      "clientSecret": "dGhpcy1pcy1hLXNlY3JldC12YWx1ZS1mb3ItdGVzdGluZw=="
    },
    "tokenCaching": {
      "enabled": true,
      "ttlSeconds": 3500
    },
    "additionalHeaders": [
      {
        "name": "X-Webhook-Secret",
        "value": "hmac-sha256-secret-value",
        "sensitive": true
      },
      {
        "name": "X-Partner-ID",
        "value": "PARTNER-BANK-001",
        "sensitive": false
      }
    ]
  }
}

{
  "url": "https://api.fintech-partner.io/webhooks/origo",
  "filterId": "43958afa-057e-4db7-a765-a5757aa42ec8",
  "authType": "OAUTH",
  "durationInDays": 90,
  "status": "ACTIVE",
  "oauthCredentials": {
    "tokenEndpoint": {
      "tokenUrl": "https://auth.fintech-partner.io/oauth/token",
      "grantType": "client_credentials",
      "scope": "events.deliver notifications.write"
    },
    "clientAuthentication": {
      "authMethod": "client_secret_post",
      "clientId": "origo-fintech-client",
      "clientSecret": "c2VjcmV0LWZvci1wb3N0LWJvZHktYXV0aGVudGljYXRpb24="
    },
    "tokenCaching": {
      "enabled": true,
      "ttlSeconds": 3500
    },
    "additionalHeaders": [
      {
        "name": "X-Webhook-Secret",
        "value": "hmac-sha256-secret-value",
        "sensitive": true
      },
      {
        "name": "X-Partner-ID",
        "value": "PARTNER-FINTECH-001",
        "sensitive": false
      }
    ]
  }
}

{
  "url": "https://api.enterprise-partner.com/callbacks/events",
  "filterId": "43958afa-057e-4db7-a765-a5757aa42ec8",
  "authType": "OAUTH",
  "durationInDays": 90,
  "status": "ACTIVE",
  "oauthCredentials": {
    "tokenEndpoint": {
      "tokenUrl": "https://auth.enterprise-partner.com/oauth2/token",
      "grantType": "client_credentials",
      "scope": "callbacks.write events.deliver"
    },
    "clientAuthentication": {
      "authMethod": "client_secret_jwt",
      "clientId": "origo-enterprise-client",
      "clientSecret": "aG1hYy1zaGFyZWQtc2VjcmV0LWZvci1qd3Qtc2lnbmluZw==",
      "clientAssertionType": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    },
    "signingKey": {
      "algorithm": "HS256"
    },
    "jwtClaims": {
      "issuer": "origo-enterprise-client",
      "subject": "origo-enterprise-client",
      "audience": "https://auth.enterprise-partner.com/oauth2/token",
      "includeJti": true,
      "includeNbf": true,
      "expiryMinutes": 5
    },
    "tokenCaching": {
      "enabled": true,
      "ttlSeconds": 3500
    },
    "additionalHeaders": [
      {
        "name": "X-Webhook-Secret",
        "value": "hmac-sha256-secret-value",
        "sensitive": true
      },
      {
        "name": "X-Partner-ID",
        "value": "PARTNER-ENTERPRISE-001",
        "sensitive": false
      }
    ]
  }
}

{
  "url": "https://api.partnerbank.com.au/callbacks/events",
  "filterId": "43958afa-057e-4db7-a765-a5757aa42ec8",
  "authType": "OAUTH",
  "durationInDays": 90,
  "status": "ACTIVE",
  "oauthCredentials": {
    "tokenEndpoint": {
      "tokenUrl": "https://mtls.partner.idp.stg.combank.com.au/as/token.oauth2",
      "grantType": "client_credentials",
      "scope": "site-administration.hid.write"
    },
    "clientAuthentication": {
      "authMethod": "private_key_jwt",
      "clientId": "site-administration.ext.stg.origo",
      "clientAssertionType": "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
    },
    "signingKey": {
      "algorithm": "ES256",
      "keyId": "fec4e7b6-aed1-4aca-8319-37594a73224f",
      "privateKeyPem": "-----BEGIN PRIVATE KEY-----\nMEECAQAwEwYHKoZIzj0CAQYIKoZIzj0DAQcEJzAlAgEBBCAQsUQFpmegjyAqbDtT\nLPhazIUcvmvq/FzzEQ8auXd5pg==\n-----END PRIVATE KEY-----"
    },
    "jwtClaims": {
      "issuer": "site-administration.ext.stg.origo",
      "subject": "site-administration.ext.stg.origo",
      "audience": "https://mtls.partner.idp.stg.combank.com.au/as/token.oauth2",
      "includeJti": true,
      "includeNbf": true,
      "expiryMinutes": 10
    },
    "tokenCaching": {
      "enabled": true,
      "ttlSeconds": 3500
    },
    "additionalHeaders": [
      {
        "name": "X-Webhook-Secret",
        "value": "hmac-sha256-secret-value",
        "sensitive": true
      },
      {
        "name": "X-Partner-ID",
        "value": "PARTNER-ENTERPRISE-00",
        "sensitive": false
      },
      {
        "name": "X-Correlation-Source",
        "value": "origo-callback-service",
        "sensitive": false
      }
    ]
  }
}

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

Callback Behaviour

Sensitive Data Handling

The httpHeader and secret properties are not returned when retrieving callback resource details. Similarly, for OAuth 2.0/JWT-based callbacks, sensitive credentials such as clientSecret, privateKeyPem, clientKeyPem, clientCertificatePem, truststorePem, and sensitive additionalHeaders values are never exposed through API responses. These values are securely stored by the platform.

Callback Delivery Behaviour

HID Origo delivers events to configured web services through callback registrations. The platform does not interpret or process the response body returned by customer endpoints and only evaluates the delivery status of the event notification.

If an event delivery attempt is unsuccessful, the event is marked as failed to ensure event data is retained. Failed events can later be retrieved through the Event Management API for further analysis or handling.

Callback Suspension and Recovery

If three consecutive delivery attempts to a registered callback URL fail, the callback registration is automatically moved to a suspended state. During suspension, HID Origo temporarily stops attempting delivery to the affected endpoint, and newly generated events are marked as failed without additional retry attempts.

HID Origo periodically checks the availability of suspended endpoints. Once the endpoint becomes reachable again, callback delivery automatically resumes.

Callback Lifecycle Management

Callback registrations follow a managed lifecycle model supporting registration, activation, suspension, reactivation, deactivation, and removal. This lifecycle-based approach provides improved operational control, reduces delivery-related issues, and helps ensure reliable event management behaviour.

Status	Description
ACTIVE	When registering a callback, it is immediately designated as ACTIVE, allowing it to start functioning and processing events right away. This ACTIVE status indicates that the registration is ready for use and will participate in the system's operations without any delay or additional steps required to activate it.
INACTIVE	To stop receiving callbacks, mark the registration as INACTIVE. In this state, Origo will not attempt to invoke the registered web service.
SUSPENDED	If HID Origo fails to deliver events to a particular web service three times consecutively, the callback registration is automatically marked as suspended. This indicates the web service may be unavailable, so the system stops attempting deliveries and marks new events as failed. HID Origo will periodically check the web service availability to resume deliveries once it becomes reachable again.
EXPIRED	Customers can set a validity period for callback registrations using the `durationInDays` property. They must renew before expiration to continue receiving callbacks. After expiration, there's a 30-day grace period for renewal; otherwise, the registration is permanently deleted.

Contact HID Professional Services for details on callback whitelisting.

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.