WSO2 OB 3 Accelerator | Event Notifications
Introduction
WSO2 Open Banking Solution has stepped in to a new era with the introduction of the accelerator model under the new version of the Open Banking Solution, WSO2 Open Banking 3(OB3).
OB3 architecture and implementation were done with the sole purpose of enabling faster specification implementation and opening more opportunities for developers who wish to add new features while being compliant with the core open banking principles. As per the name itself, OB3 accelerator has accelerated the implementation process for partners in different regions and helped Banks achieve their open bank competencies faster than ever.
The event Notification feature was added to OB3 Accelerator after studying the IETF Security Event Token(SET) and IETF Poll-Based Security Event Token (SET) Delivery Using HTTP specifications. A more generalized implementation of the above mentioned two specifications is available with the ability to extend those features to suite specific toolkits.
A frequent use case is utilizing the event notifications API to notify the state change of a consent resource. For an example a notification can be generated for a state change such as the consent being authorized or for the revocation of an authorized consent.
A Security Event Token(SET)
Given below is the abstract obtained from the IETF Security Event Notification Specification which gives a good understanding of what a SET is. A single SET can contain multiple events relevant to a single client id. A single SET must be in either of the 3 statuses, open, acknowledged or error.
"This specification defines the Security Event Token (SET) data structure. A SET describes statements of fact from the perspective
of an issuer about a subject. These statements of fact represent an
event that occurred directly to or about a security subject, for
example, a statement about the issuance or revocation of a token on
behalf of a subject. This specification is intended to enable
representing security- and identity-related events. A SET is a JSON
Web Token (JWT), which can be optionally signed and/or encrypted.
SETs can be distributed via protocols such as HTTP.Architecture
Following is the high level architecture diagram of the event notification feature.
Creating and Polling Event Notifications
As mentioned earlier, this feature is added as an internal API to the OB Accelerator. The API comes with two endpoints, an event creation endpoint and an event polling endpoint. Both these endpoints are POST endpoints, secured with basic authentication and accept base64 encoded JSON strings as payload.
If you take a look at the architecture diagram provided you can see that the Event Creation API is not exposed to the API Gateway. This is because the Event Creation endpoint would be invoked by the ASPSP(Ex: Bank Entity) and hence it is advised not to expose it to the TPP(Third Party Providers).
The event creation API enables a toolkit developer to decide their own event types and the data which they want to capture for a specific event. A guideline for these would be an events notifications specification released by the particular governing body for open banking in the developers’ geographical area of concern.
Event polling API enables polling of events relevant to a specific client id and this API is used to get events, acknowledge received events and set error to events which contain errors. One or all three tasks can be done in a single poll request depending on the requirement. In the polling payload setting the maxEvents = 0 means the user only wants to know if there are open events available for a specific client ID.
You can try out the feature and get sample payloads for event creation and polling in the official WSO2 Open Banking Documentation.
Extension Points for Developers
There are 3 extension points for the toolkit developers to extend the default behavior of this API to suit the needs of their specifications. Given below are them. The relevant configurations to obtain custom methods are documented in the WSO2 OB Documentation
EventCreationServiceHandler interface
- publishOBEvents method: store event-related data in the accelerator database
EventPollingServiceHandler interface
- pollEvents method: provide both positive and negative event acknowledgements
EventNotificationGenerator interface
- generateEventNotificationBody method: generate the event notification body
- generateEventNotification method: generate the event notification JWT
Developers can find further information about the customization of the extensions points at WSO2 OB Documentation
