Lifecycle Management Events
This specification provides details and schemas of events available by the platform to the issuer.
Event Delivery model
Events are pushed as opposed to traditional pulling. Customers are expected to expose endpoints to receive events with the following constraints:
- HTTP POST + JSON content
- Authentication supported is mTLS and/or oAuth2 The delivery model is At least once delivery which means that at events will be delivered at least once within reasonable time. Endpoints are however expected to be idempotent and tolerant reader to support forward compatibility.
Retry Logic and Retention
After forwarding an event to the Issuer, the Event hub implements the following retry logic depending on the HTTP response from the Issuer's Backend:
- An HTTP 2xx response acknowledges reception of the event. Endpoint must ensure storage or full business processing before acknowledgement.
- An HTTP 4xx response from Issuer will either retry or abort. This is configurable.
- An HTTP 5xx response will always retry. If the Event hub fails to notify a subscriber endpoint, it will retry calling the subscriber endpoint with a default retry frequency once per second; retries continue for a retry limit of 2 hours. If the subscriber cannot be notified after 2 hours, an alarm is raised requiring manual intervention to resolve. Resolution involves correcting the issue that is preventing events from being sent to the subscriber, and then resending all events going back to the time of initial failure. This may include resending events which were properly sent if the initial failure was intermittent. As the same event may be re-sent multiple times during resolution, the subscriber endpoint’s handling of an event must be idempotent. Resolution must be completed within the retention period, which is 1 day by default, otherwise the events are permanently lost.
Note
The retry frequency is configurable and is intended to prevent retries from overwhelming the Issuer’s subscriber endpoints. The default is 1 retry per second. The 2-hour retry limit is enforced by the Event hub and cannot be increased. The retention period is configurable and is intended to limit data retention. The default is 1 day.
Event structure
All event are structured in the same manner
- Common header
- Specific payload depending on the event type
Subscription model
Event subscriptions are not self-service. To receive lifecycle events, you must expose a subscriber endpoint and request registration with IDEMIA's SRE team.
Endpoint topology
You are not limited to a single subscriber endpoint. Each event type can be routed to a different HTTPS endpoint and context path, allowing you to align event delivery with your backend topology.
Common patterns include:
- Single endpoint — one URL receives all subscribed event types. Suitable for simple integrations or when a single service handles all lifecycle processing.
- Per-domain endpoints — separate URLs for logically distinct groups, for example:
/events/issuance— receivesmIDIssued,mIDClaimed,mIDIssuanceFailed/events/state— receivesmIDStateUpdated,mIDDeviceStatusUpdated,mIDStateUpdateFailed,mIDDeviceStatusUpdateFailed/events/mso— receivesMobileSecurityObjectsIssued
- Per-event endpoints — one URL per event type, for fine-grained routing to individual microservices.
Each registered endpoint has its own authentication configuration (mTLS or OAuth2). Authentication does not need to be the same across endpoints.
What to provide when requesting registration
For each endpoint you want to register, submit the following to your IDEMIA partner manager, who will forward it to the SRE team:
Item | Details |
|---|---|
| Endpoint URL | Full HTTPS URL including context path (e.g. https://issuer.example.com/webhooks/issuance). One URL per environment (sandbox, production). |
| Event types | The specific event types this endpoint should receive (e.g. mIDIssued, mIDClaimed). Each event type can only be routed to one endpoint per environment. |
| Authentication method | mTLS — provide the client certificate, or OAuth2 — provide client credentials (client ID and secret) |
| Contact email | An operational contact address for delivery failure alerts |
If you are registering multiple endpoints, provide a separate entry for each URL with its associated event types and authentication details.
After registration
Once registration is confirmed by IDEMIA:
- Events of the subscribed types will be pushed to the registered endpoint automatically as they are produced by the platform.
- To subscribe to additional event types, register a new endpoint, or change routing, submit a new request to your partner manager.
- To deregister an endpoint, contact your partner manager.
Lifecycle Events
In order to make use of the API, please log in