Version Control

The Callback URL API Specification described here allows a TPP to:

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

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 URL for TPP hosted services to receive event notifications from an ASPSP. The 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 Callback URL 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.

Endpoints

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

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.

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

Usage Examples

Create Callback Url

Get Callback Urls

Swagger Specification

The Swagger Specification for Callback URL API can be downloaded from the following links:

• JSON
• YAML