Event Notification API Specification - v3.1

Version Control

VersionDateAuthorComments
3.0 OB R/W API TeamSwagger URLs updated to point to latest stable version.
3.1-draft1 OB R/W API Team

This is the initial draft version for 3.1

Errata:

Typos and grammar fixes.

Removed duplicate ASPSP Swagger specification section.

3.1-draft2 OB R/W API Team

Draft2 Changes:

  • Updated example URLs to version 3.1.
  • Update usage examples with Links and Meta sections.
3.1-draft3 OB R/W API Team

Draft3 Changes

  • Swagger Specification links updated
3.1-draft4 OB R/W API Team

Draft4 Changes

  • Swagger Specification links updated
3.1-RC1 OB R/W API Team

RC1 Changes

  • Changes in data model and example to reflect that iat and toe should be xs:int.
  • Swagger Specification links updated
3.1OB R/W API Team

Version 3.1 final release.

No changes from Version 3.1 RC1.

 Updated swagger links to latest release candidate.

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: 

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

ResourceHTTP OperationEndpointMandatory ?ScopeGrant TypeMessage SigningIdempotency KeyRequest ObjectResponse Object
callback-urlPOSTPOST /callback-urlsOptional

accounts

payments

fundsconfirmations

Client Credentials

Signed Request

Signed Response

NoOBCallbackUrl1OBCallbackUrlResponse1
callback-urlGETGET /callback-urlsMandatory (if resource POST implemented)

accounts

payments

fundsconfirmations

Client CredentialsSigned ResponseNon/aOBCallbackUrlsResponse1
callback-urlPUTPUT /callback-urls/{CallbackUrlId}Mandatory (if resource POST implemented)

accounts

payments

fundsconfirmations

Client Credentials

Signed Request

Signed Response

NoOBCallbackUrlResponse1OBCallbackUrlResponse1
callback-urlDELETEDELETE /callback-urls/{CallbackUrlId}Mandatory (if resource POST implemented)

accounts

payments

fundsconfirmations

Client Credentialsn/aNon/an/a

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

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBCallbackUrl1OBCallbackUrl1OBCallbackUrl1



Data1..1OBCallbackUrl1/DataOBCallbackUrlData1


Url1..1OBCallbackUrl1/Data/UrlCallback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to.xs:anyURI

Version1..1OBCallbackUrl1/Data/VersionVersion for the event notification.Max10Text

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

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBCallbackUrlResponse1OBCallbackUrlResponse1OBCallbackUrlResponse1



Data1..1OBCallbackUrlResponse1/DataOBCallbackUrlResponseData1


CallbackUrlId1..1OBCallbackUrlResponse1/Data/CallbackUrlIdUnique identification as assigned by the ASPSP to uniquely identify the callback URL resource.Max40Text

Url1..1OBCallbackUrlResponse1/Data/UrlCallback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to.xs:anyURI

Version1..1OBCallbackUrlResponse1/Data/VersionVersion for the event notification.Max10Text

Callback Urls - Response

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

  • GET /callback-urls

UML

Data Dictionary

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBCallbackUrlsResponse1OBCallbackUrlsResponse1OBCallbackUrlsResponse1



Data1..1OBCallbackUrlsResponse1/DataOBCallbackUrlsResponseData1


CallbackUrl0..nOBCallbackUrlsResponse1/Data/CallbackUrlOBCallbackUrlResponseData1


CallbackUrlId1..1OBCallbackUrlsResponse1/Data/CallbackUrl/CallbackUrlIdUnique identification as assigned by the ASPSP to uniquely identify the callback url resource.Max40Text

Url1..1OBCallbackUrlsResponse1/Data/CallbackUrl/UrlCallback URL for a TPP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to.xs:anyURI

Version1..1OBCallbackUrlsResponse1/Data/CallbackUrl/VersionVersion for the event notification.Max10Text

ASPSP Usage Examples

Create Callback Url

POST /callback-urls

Callback Url Request
POST /callback-urls HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==
x-fapi-financial-id: OB/2017/001
x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865
Content-Type: application/json
Accept: application/json

{
  "Data": {
	"Url": "https://tpp.com/open-banking/v3.1/event-notifications",
	"Version": "3.1"
  }
}

POST /callback-urls response

Callback Url Response
HTTP/1.1 201 Created
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865
Content-Type: application/json

{
	"Data": {
		"CallbackUrlId": "CB-101",
		"Url": "https://tpp.com/open-banking/v3.1/event-notifications",
		"Version": "3.1"
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking/v3.1/callback-urls/CB-101"
	},
	"Meta": {}
}


Get Callback Urls

GET /callback-urls

GET Callback Url Request
GET /callback-urls HTTP/1.1
Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA
x-fapi-financial-id: OB/2017/001
x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865
Accept: application/json

GET /callback-urls response

GET Callback Url Response
GET/1.1 200 OK
x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865
Content-Type: application/json

{
	"Data": {
		"CallbackUrl": [{
			"CallbackUrlId": "CB-101",
			"Url": "https://tpp.com/open-banking/v3.1/event-notifications",
			"Version": "3.1"
		}]
	},
	"Links": {
		"Self": "https://api.alphabank.com/open-banking/v3.1/callback-urls/"
	},
	"Meta": {}
}




ASPSP Swagger Specification

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

TPP Endpoints

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

Endpoints

ResourceHTTP OperationEndpointMandatory ?ScopeGrant TypeMessage SigningIdempotency KeyRequest ObjectResponse Object
event-notificationPOSTPOST /event-notificationsOptionaln/an/a

Signed Request

NoOBEventNotification1

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

NameOccurrenceXPathEnhancedDefinitionClassCodesPattern
OBEventNotification1OBEventNotification1The resource-update event.OBEventNotification1


iss1..1OBEventNotification1/issIssuer.xs:anyURI

iat1..1OBEventNotification1/iatIssued At (Unix timestamp).xs:int

jti1..1OBEventNotification1/jtiJWT ID.Max128Text

aud1..1OBEventNotification1/audAudience.Max128Text

sub1..1OBEventNotification1/subSubject.xs:anyURI

txn1..1OBEventNotification1/txnTransaction Identifier.Max128Text

toe1..1OBEventNotification1/toeTime of Event (Unix timestamp).xs:int

events1..1OBEventNotification1/eventsEvents.OBEvent1

urn:uk:org:openbanking:events:resource-update1..1OBEventNotification1/events/urn:uk:org:openbanking:events:resource-updateResource-Update Event.OBEventResourceUpdate1

subject1..1OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subjectThe resource-update event.OBEventSubject1

subject_type1..1OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject/subject_typeSubject type for the updated resource. Max128Texthttp://openbanking.org.uk/rid_http://openbanking.org.uk/rty
http://openbanking.org.uk/rid1..1OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject/http://openbanking.org.uk/ridResource Id for the updated resource.Max128Text

http://openbanking.org.uk/rty1..1OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject/http://openbanking.org.uk/rtyResource Type for the updated resource.Max128Text

http://openbanking.org.uk/rlk1..nOBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject/http://openbanking.org.uk/rlkResource links to other available versions of the resource.OBEventLink1

version1..1OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject/http://openbanking.org.uk/rlk/versionResource version.Max10Text

link1..1OBEventNotification1/events/urn:uk:org:openbanking:events:resource-update/subject/http://openbanking.org.uk/rlk/linkResource link.xs:anyURI

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

POST /event-notifications

Event Notification Request
POST /event-notifications HTTP/1.1
x-fapi-financial-id: OB/2018/002
x-fapi-interaction-id: 14ba1762-a316-4a87-8d6e-5bfbefaf01d7
Content-Type: application/jwt

eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGViYW5rLmNvbS8iLCJpYXQiOiIxNTE2MjM5MDIyIiwianRpIjoiYjQ2MGEwN2MtNDk2Mi00M2QxLTg1ZWUtOWRjMTBmYmI4ZjZjIiwic3ViIjoiaHR0cHM6Ly9leGFtcGxlYmFuay5jb20vYXBpL29wZW4tYmFua2luZy92My4wL3Bpc3AvZG9tZXN0aWMtcGF5bWVudHMvcG10LTcyOTAtMDAzIiwiYXVkIjoiN3VteDVuVFIzMzgxMVF5UWZpIiwiZXZlbnRzIjp7InVybjp1azpvcmc6b3BlbmJhbmtpbmc6ZXZlbnRzOnJlc291cmNlLXVwZGF0ZSI6eyJzdWJqZWN0Ijp7InN1YmplY3RfdHlwZSI6Imh0dHA6Ly9vcGVuYmFua2luZy5vcmcudWsvcmlkX2h0dHA6Ly9vcGVuYmFua2luZy5vcmcudWsvcnR5IiwiaHR0cDovL29wZW5iYW5raW5nLm9yZy51ay9yaWQiOiJwbXQtNzI5MC0wMDMiLCJodHRwOi8vb3BlbmJhbmtpbmcub3JnLnVrL3J0eSI6ImRvbWVzdGljLXBheW1lbnQiLCJodHRwOi8vb3BlbmJhbmtpbmcub3JnLnVrL3JsayI6W3sidmVyc2lvbiI6InYzLjAiLCJsaW5rIjoiaHR0cHM6Ly9leGFtcGxlYmFuay5jb20vYXBpL29wZW4tYmFua2luZy92My4wL3Bpc3AvZG9tZXN0aWMtcGF5bWVudHMvcG10LTcyOTAtMDAzIn0seyJ2ZXJzaW9uIjoidjEuMSIsImxpbmsiOiJodHRwczovL2V4YW1wbGViYW5rLmNvbS9hcGkvb3Blbi1iYW5raW5nL3YxLjEvcGF5bWVudHMvcG10LTcyOTAtMDAzIn1dfX19LCJ0eG4iOiJkZmM1MTYyOC0zNDc5LTRiODEtYWQ2MC0yMTBiNDNkMDIzMDYiLCJ0b2UiOiIxNTE2MjM5MDIyIn0.-coUJsJVycbZufiWHi71TIQsCjP4gj9uZ4FOsNEysZ4
Decoded JWT Body - Event Notification Payload
{
  "iss": "https://examplebank.com/",
  "iat": 1516239022,
  "jti": "b460a07c-4962-43d1-85ee-9dc10fbb8f6c",
  "sub": "https://examplebank.com/api/open-banking/v3.1/pisp/domestic-payments/pmt-7290-003",
  "aud": "7umx5nTR33811QyQfi",
  "events": {
    "urn:uk:org:openbanking:events:resource-update": {
      "subject": {
        "subject_type": "http://openbanking.org.uk/rid_http://openbanking.org.uk/rty",
        "http://openbanking.org.uk/rid": "pmt-7290-003",
        "http://openbanking.org.uk/rty": "domestic-payment",
        "http://openbanking.org.uk/rlk": [
          {
            "version": "v3.1",
            "link": "https://examplebank.com/api/open-banking/v3.1/pisp/domestic-payments/pmt-7290-003"
          },
          {
            "version": "v1.1",
            "link": "https://examplebank.com/api/open-banking/v1.1/payment-submissions/pmt-7290-003"
          }
        ]
      }
    }
  },
  "txn": "dfc51628-3479-4b81-ad60-210b43d02306",
  "toe": 1516239022
}

POST /event-notifications response

Event Notification Response
HTTP/1.1 202 Accepted
x-fapi-interaction-id: 14ba1762-a316-4a87-8d6e-5bfbefaf01d7

TPP Swagger Specification

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