Version Control

Overview

The Event Notification API Specification describes the flows and payloads to allow ASPSPs to deliver event notifications to TPPs. 

The ASPSP API endpoints described here allow a TPP to:

• Register a callback URL with an ASPSP to receive event notifications.
• Optionally read, update or delete a registered callback URL.

The TPP API endpoint described here allow an ASPSP to:

• Notify a TPP that an event has occurred.

This specification should be read in conjunction with the Payments, Accounts, and Confirmation of Funds API specifications. These specifications detail the circumstances under which an event notification may be delivered.

Implementation of the Event Notification API Specification is optional for both ASPSPs and TPPs.

Design Principles

Security Event Token Alignment

Event notifications are aligned with the Security Event Token standard, a proposed IETF standard for exchanging information about security events. See https://tools.ietf.org/html/rfc8417. An event notification is structured as a JWT, indicating an event has occurred through a set of claims.

A resource-update event (rurn:uk:org:openbanking:events:resource-update) is used to communicate that a specific resource has been updated. It contains identifiers for the resource and links to retrieve it.

Event Notification Message Signing

Event Notifications are singed for non-repudiation using the approach defined in the R/W API specification, with the following difference:

• The JWT's signature (JWS) is sent in the HTTP body of the request, as opposed to a detached JWS sent in the HTTP header.

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 Configuration

• This flow begins with a TPP creating a callback-url resource with an ASPSP.
• The callback URL must be specified at this stage.

Step 2: Event Notification Required

• When an event occurs on a resource that requires a notification, the ASPSP identifies the callback-url associated with the TPP owning the affected resource.
• The ASPSP sends the event notification to the callback URL, detailing the nature of the event and identifying the affected resource.
• The TPP initiates a client credential grant and retrieves the resource using the details contained in the event notification.

Step 3: Retrieve/Update/Delete Event Notification Configuration

• The TPP may optionally read/update/delete the callback-url 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 Notification Configuration
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 /callback-urls
ASPSP Resource Server -> TPP: HTTP 201 (Created),  CallbackUrlId

note over TPP, ASPSP Notification Service
 Step 2: Event Notification Required
end note



note left of ASPSP Notification Service
- Create EventNotification
- Sign EventNotification
end note

loop Retry Until Successful (as per retry policy)
ASPSP Notification Service -> TPP: POST /event-notifications, EventNotification, signature
alt success
TPP -> ASPSP Notification Service: HTTP 202 Accepted
else failure
TPP -> ASPSP Notification Service: HTTP 500/400 
end alt
end loop

note right of TPP
TPP verifies signature

URL for resource contained in the 
EventNotification rlk (resource links) claim
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: GET Resource
ASPSP Resource Server -> TPP: HTTP 200 (OK),  Resource

note over TPP, ASPSP Notification Service
Step 3: Retrieve/Update/Delete Event Notification Configuration
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 /callback-urls
ASPSP Resource Server -> TPP: HTTP 200 (OK)
else Update
TPP -> ASPSP Resource Server: PUT /callback-urls/{CallbackUrlId}
ASPSP Resource Server -> TPP: HTTP 200 (OK)
else Delete
TPP -> ASPSP Resource Server: DELETE /callback-urls/{CallbackUrlId}
ASPSP Resource Server -> TPP: HTTP 204 (OK)
end alt
option footer=bar

Callback URL

TPPs must register a callback URL for TPP hosted services to receive event notifications from an ASPSP. The callback URL 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

Release Management

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

Callback-URL Resource

TPPs must register for event-notification callbacks with the version of Event Notification API they have implemented. The version element of the Callback-URL resource is used for this purpose.

POST

• A TPP must only create a callback-url on one version

GET

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

PUT

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

DELETE

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

Callback-URL per TPP

An ASPSP will maintain at most, a single Callback-URL resource per TPP.

Transport Level Security - TPP Endpoints

TPP hosted endpoints must be protected using TLS 1.2, as per the FAPI R/W specification (details here http://openid.net/specs/openid-financial-api-part-2-ID1.html#tls-considerations).

TPP hosted endpoints must be protected using an OB issued network certificate.

MA-TLS is not applicable to TPP hosted endpoints.

ASPSP Endpoints

A TPP will set up and maintain its call back details (URL and version number) using the callback-url resource.

Endpoints

POST /callback-urls 

POST /callback-urls

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

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

GET /callback-urls

GET /callback-urls

The API endpoint allows the TPP to ask an ASPSP to retrieve its callback-url resource.

• The ASPSP retrieves the callback-url resource and responds with the resource.

PUT /callback-urls/{CallbackUrlId}

PUT /callback-urls/{CallbackUrlId}

The API endpoint allows the TPP to ask an ASPSP to update a callback-url resource.

• The PUT action allows the TPP to update a callback URL for an ASPSP to send event notifications to.
• The ASPSP updates the callback-url resource and responds with the updated resource.

DELETE /callback-urls/{CallbackUrlId}

DELETE /callback-urls/{CallbackUrlId}

The API endpoint allows the TPP to ask an ASPSP to delete a callback-url resource.

• The ASPSP deletes the callback-url resource.

ASPSP Data Model

Callback Url - Request

The OBCallbackurl1 object will be used for the call to:

• POST /callback-urls

UML Diagram

Data Dictionary

Callback Url - Response

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

• POST /callback-urls
• PUT /callback-urls/{CallbackUrlId}

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

• PUT /callback-urls

UML

Data Dictionary

Callback Urls - Response

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

• GET /callback-urls

UML

Data Dictionary

ASPSP Usage Examples

Create Callback Url

Get Callback Urls

ASPSP Swagger Specification

The Swagger Specification for Event Notification ASPSP APIs can be downloaded from the following links:

• JSON
• YAML

TPP Endpoints

An ASPSP will send event notifications to a TPP using the event-notification resource.

Endpoints

Notes:

• A TPP must make available a callback notification endpoint to receive event notifications.
• A TPP must acknowledge an event notification with a 202 HTTP response and include the provided x-fapi-interaction-id.

POST /event-notifications

POST /event-notifications

The API endpoint allows the ASPSP to send an event-notification resource to a TPP.

TPP Data Model

Event Notification - Request

The OBEventNotification1 object will be used for a call to:

• POST /event-notifications

The OBEventNotification1 object is aligned with the Security Event Token (https://tools.ietf.org/html/rfc8417). It contains a single OBEventResourceUpdate1 event object within the events claim.

UML Diagram

The rid, rty and rlk claims are prefixed with the OB namespace http://openbanking.org.uk in the data model. The namespace has been removed from the diagram for clarity.

Notes

For the OBEventNotification1 object:  

• The array of resource links (http://openbanking.org.uk/rlk) must contain links to all supported versions of the resource.

Data Dictionary

Event Notification Retry Policy

ASPSP

An ASPSP's Event Notification Retry Policy defines behaviour when an event notification is unacknowledged or the ASPSP receives a 5xx error.

• An Event Notification Retry Policy must define an Exponential Backoff Policy to calculate the Retry Time Interval.
• An Event Notification Retry Policy must define the Maximum Number of Retries an ASPSP will make before declaring the TPP Event Notification endpoint unresponsive and ceasing further attempts.
• An Event Notification Retry Policy must define the Maximum Time Interval for Retries, after which an ASPSP will declare the TPP Event Notification endpoint unresponsive and cease further attempts.

TPP

A TPP may make GET requests for its resources if its /event-notifications endpoint was unavailable for the Maximum Time Interval for Retries, as defined in an ASPSP's Event Notification Retry Policy.

TPP Usage Examples

Send Event Notification

TPP Swagger Specification

The Swagger Specification for Event Notification TPP APIs can be downloaded from the following links:

• JSON
• YAML