Updated MSD to make clear a GET request for the updated resource is made by the TPP
Added Event Notification Retry Policy
Rename Scope (Any) to Scope for consistency with other specifications
Added that ASPSP will maintain at most a single Callback-URI resource per TPP
Removed CallbackUrlId from GET endpoint, and created an associated response. Updated usage example.
Renamed to callback-url for consistency.
Added Release Management specification for the /callback-urls endpoint
Added Transport Level Security - TPP Endpoints section to Basics.
Added Swagger specifications.
OB R/W API Team
Updated MSD to clarify URL is retrieved from rlk claim.
Swapped the class names in the data dictionary for urn:uk:org:openbanking:events:resource-update and subject
Clarified that resource links must be populated for all supported versions of a resource.
Added Swagger-based API specification encoded in JSON and YAML.
OB R/W API Team
Swagger URLs updated to point to latest stable version.
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 optionalfor both ASPSPs and TPPs.
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.
The steps and sequence diagram below provide a general outline of a notification flow for all resources in the R/W APIs.
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.
The TPP may optionally read/update/delete the callback-url resource.
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'.