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

Open

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.0/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 request PUT 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 request PUT 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 

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

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}

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}

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

Open

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

Open

Data Dictionary

Callback Urls - Response

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

• GET /callback-urls

UML

Open

Data Dictionary