Version Control

Overview

The Event Notification Subscription API Specification describes the flows and payloads to allow TPPs to subscribe to events with an ASPSP.

The ASPSP API endpoints described here allow a TPP to:

• Register an event subscription with an ASPSP to subscribe to event notifications.
  • A subscription can enable real time event notifications via a HTTP callback from the ASPSP, and aggregated polling by the TPP.
• Specify a list of event types to be notified on. 
• Optionally read, update or delete a registered event subscription.

Basics

Overview

The steps and sequence diagram below provide a general outline of a notification flow for all resources in the R/W APIs.

Steps

Step 1: Setup Event Notification Subscription

• This flow begins with a TPP creating an event-subscription resource with an ASPSP.

Step 2: Retrieve/Update/Delete Event Notification Subscription

• The TPP may optionally read/update/delete the event-subscription resource.

Sequence Diagram

participant TPP
participant ASPSP Authorisation Server
participant ASPSP Resource Server
participant ASPSP Notification Service
    
note over TPP, ASPSP Notification Service
Step 1: Setup Event Subscription
end note

TPP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
TPP -> ASPSP Authorisation Server: Initiate Client Credentials Grant
ASPSP Authorisation Server -> TPP: access-token
TPP <-> ASPSP Resource Server: Establish TLS 1.2 MA
TPP -> ASPSP Resource Server: POST /event-subscriptions
ASPSP Resource Server -> TPP: HTTP 201 (Created),  EventSubscriptionId

note over TPP, ASPSP Notification Service
Step 2: Retrieve/Update/Delete Event Subscription
end note

TPP <-> ASPSP Authorisation Server: Establish TLS 1.2 MA
TPP -> ASPSP Authorisation Server: Initiate Client Credentials Grant
ASPSP Authorisation Server -> TPP: access-token
TPP <-> ASPSP Resource Server: Establish TLS 1.2 MA
alt Retrive
TPP -> ASPSP Resource Server: GET /event-subscriptions
ASPSP Resource Server -> TPP: HTTP 200 (OK)
else Update
TPP -> ASPSP Resource Server: PUT /event-subscriptions/{EventSubscriptionId}
ASPSP Resource Server -> TPP: HTTP 200 (OK)
else Delete
TPP -> ASPSP Resource Server: DELETE /event-subscriptions/{EventSubscriptionId}
ASPSP Resource Server -> TPP: HTTP 204 (OK)
end alt
option footer=bar

Subscriptions for Real Time Event Notifications and Aggregated Polling

ASPSPs may choose to offer Real Time Notifications, Aggregated Polling or a combination of both. TPPs will subscribe to the different notification mechanisms using the event-subscription resource.

Real Time Event Notifications

TPPs must register an event subscription with a CallbackUrl for TPP hosted services to receive real time event notifications from an ASPSP (providing an ASPSP supports this functionality).

The CallbackUrl must end with the Event Notification API specification version number, followed by ‘/event-notifications'.

For example: 

• URL: https://tpp.com/open-banking/v3.1/event-notifications

Aggregated Polling

TPPs must register an event subscription to enable aggregated polling on an ASPSP (providing an ASPSP supports this functionality).

Release Management

This section overviews the release management and versioning strategy for the Event Notification API.

Event-Subscription Resource

TPPs must register for event-subscriptions with the version of Event Notification API they have implemented. The version field of the event-subscription resource is used for this purpose.

POST

• A TPP must only create an event-subscription on one version

GET

• A TPP must not access a event-subscription on an older version, via the EventSubscriptionId for an event-subscription created in a newer version.
  • E.g., a event-subscription created in v4, accessed via v3.
• An ASPSP must allow an event-subscription resource to be accessed in a newer version.
• An ASPSP must ensure event-subscription fields are unchanged when accessed in a different version.

PUT

• A TPP must not update an event-subscription on an older version via a EventSubscriptionId created in a newer version.
• E.g., A event-subscription is created in v4, and a PUT request on v3.
• An ASPSP must support updating an event-subscription from a previous version via a EventSubscriptionId created in a newer version.
• E.g., A event-subscription is created in v3, and a PUT request on v4.

DELETE

• A TPP must not delete an event-subscription on an older version via a EventSubscriptionId created in a newer version.
• E.g. An event-subscription is created in v4, and request DELETE on v3.
• An ASPSP must support deleting an event-subscription from a previous version via a EventSubscriptionId created in a newer version.
• E.g., An event-subscription is created in v3, and request DELETE on v4.

Event-Subscription per TPP

An ASPSP will maintain at most, a single event-subscription resource per TPP.

Endpoints

A TPP will set up and maintain its event subscription details (URL, event types and version number) using the event-subscription resource.

Endpoints

POST /event-subscriptions 

POST /event-subscriptions

The API endpoint allows the TPP to ask an ASPSP to create a new event-subscription resource.

• The POST action allows the TPP to register an event subscription for a TPP to access event notifications.
• The ASPSP creates the event-subscription resource and responds with a unique EventSubscriptionId to refer to the resource.
• An ASPSP must respond with a 409 error if an event-subscription exists for that TPP.

GET /event-subscriptions

GET /event-subscriptions

The API endpoint allows the TPP to ask an ASPSP to retrieve its event-subscription resource.

• The ASPSP retrieves the event-subscription resource and responds with the resource.

PUT /event-subscriptions/{EventSubscriptionId}

PUT /event-subscriptions/{EventSubscriptionId}

The API endpoint allows the TPP to ask an ASPSP to update an event-subscription resource.

• The PUT action allows the TPP to update an event subscription for a TPP to access event notifications.
• The ASPSP updates the event-subscription resource and responds with the updated resource.

DELETE /event-subscriptions/{EventSubscriptionId}

DELETE /event-subscriptions/{EventSubscriptionId}

The API endpoint allows the TPP to ask an ASPSP to delete an event-subscription resource.

• The ASPSP deletes the event-subscription resource.

Data Model

Event Subscription - Request

The OBEventSubscription1 object will be used for the call to:

• POST /event-subscriptions

UML Diagram

Notes

For the OBEventSubscription1 object:

• EventTypes usage:
  • TPPs may provide a list of event types to subscribe to specific events.
  • TPPs may omit this field to subscribe to all supported events.

Data Dictionary

Event Subscription - Response

The OBEventSubscriptionResponse1 object will be used for a response to a call to:

• POST /event-subscriptions
• PUT /event-subscriptions/{EventSubscriptionId}

The OBEventSubscriptionResponse1 object will also be used for the call to:

• PUT /event-subscriptions

UML

Data Dictionary

Event Subscriptions - Response

The OBEventSubscriptionsResponse1 object will be used for a response to a call to:

• GET /event-subscriptions

UML

Data Dictionary

Usage Examples

Create Event Subscription

Get Event Subscriptions

Swagger Specification

The Swagger Specification for Event Notification Subscription API can be downloaded from the following links:

• JSON
• YAML