React to Events

UniCore creates an event for every action that happens in the system, for example when a credential offer was accepted by the recipient or when a presentation was verified. Instead of polling the API for status changes, your application can react to these events.

There are two ways to receive events:

Method	Best suited for
HTTP event publisher (webhook)	Backend systems that need to be notified reliably about specific events
Server-Sent Events (GET /v0/events)	Live feeds, e.g. an activity view in a user interface

HTTP event publisher

UniCore can push events to an HTTP endpoint of your choice. Configure one or more targets under event_publishers.http in your config.yaml and select the events you are interested in:

event_publishers:
  http:
    - enabled: true
      target_url: 'https://my-domain.example.org/event-subscriber'
      headers:
        authorization: Basic YWxhZGRpbjpvcGVuc2VzYW1l
      events:
        offer: [CredentialRequestVerified]
        authorization_request: [OID4VPAuthorizationResponseVerified]

Each event is sent as a POST request with the event as JSON in the body. See Events for the request format and a list of all available events.

Common events

You want to know when...	Event group	Event
a credential was created	credential	UnsignedCredentialCreated
a recipient requested their credential from an offer	offer	CredentialRequestVerified
a wallet presented a credential that was verified	authorization_request	OID4VPAuthorizationResponseVerified
your organization received a credential offer	received_offer	CredentialOfferReceived

Server-Sent Events

GET /v0/events streams events as CloudEvents via Server-Sent Events. You can filter the stream by types, sources and subject, and replay recent events with limit, since and until.

warning

The stream is a live feed, not a source of truth. A reconnecting subscriber may miss events. If you need a consistent state (e.g. for syncing or auditing), reconcile against the REST endpoints.