# # Event Notification API Profile - v4.0-draft1

- Overview
  - Design Principles
    - Security Event Token Alignment
    - Event Notification Message Signing
    - SET Aggregation Alignment
- Basics
  - Overview
    - Steps
    - Sequence Diagram
  - Event Types and Extensibility
  - Event-Notification Backwards Compatibility

## # Overview

The Event Notification API Profile describes the flows and common functionality to allow a TPP to receive event notifications.

The Event Notification Subscription API Profile and the Callback URL API Profile provide alternative mechanisms for TPPs to register for event notifications.

- The Event Notification Subscription API allows TPPs to register to receive all or specific event types via the Real Time Event Notification API and/or the Aggregated Polling API.
- The Callback URL API allows TPPs to register to receive a `urn:uk:org:openbanking:events:resource-update` event notification via the Real Time Event Notification API.

Usage of the Event Notification Subscription API is recommended over the Callback URL API for notification registrations. Note, should an ASPSP choose to provide both APIs for event notification registrations, any registration made using the Event Notification Subscription API supersedes a registration made using the Callback URL API.

This profile should be read in conjunction with the other API profiles which detail the circumstances under which an event notification may be delivered.

Implementation of real-time push Notifications 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
(opens new window). An event notification is structured as a JWT, indicating an event has occurred through a set of claims.

A resource-update event (`urn: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 signed 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.

#### # SET Aggregation Alignment

Aggregated polling of Security Event Tokens is aligned with the draft "Poll-Based Security Event Token (SET) Delivery Using HTTP" standard (draft-ietf-secevent-http-poll-01) as defined here: https://datatracker.ietf.org/doc/draft-ietf-secevent-http-poll/
(opens new window).

draft-ietf-secevent-http-poll-01 imposes the following constraints on the underlying SETs:

- They are JSON Web Signatures.
- They must implement the `jti` claim (JWT Identifier).

JSON API is not implemented for consistency with draft-ietf-secevent-http-poll-01.

## # Basics

### # Overview

The steps and sequence diagram below provide a general outline of a notification flow for all resources in the R/W APIs.

In this outline TPP registration for event notifications is performed using the Event Notification Subscription API.

#### # Steps

Step 1: Setup Event Notification Subscription

- This flow begins with a TPP creating an event-subscription resource with an ASPSP. This may optionally contain a callback url, and a series of event types.

Step 2: Deliver Event Notification

- An event corresponding to one of an ASPSP's event types occurs on a resource.

Step 2a: ASPSP Sends Real Time Event Notification

- A TPP must have provided a callback URL with the event-subscription resource in order to receive the real time event notification.
- The ASPSP sends a signed event notification to the callback URL, detailing the nature of the event and identifying the affected resource.
- The TPP may optionally initiate a client credential grant to retrieve the resource using the details contained in the event notification.

Step 2b: TPP Requests Event Notifications

- A TPP may request event notifications using aggregated polling.

Step 3: Retrieve/Update/Delete Event Notification Subscription

- A TPP may Retrieve/Update/Delete the event notification subscription.

#### # Sequence Diagram

Diagram source

    participant TPP
    participant ASPSP Authorisation Server
    participant ASPSP Resource Server
    participant ASPSP Notification Service
    participant ASPSP Event Polling Service

    note over TPP, ASPSP Event Polling Service
    Step 1: Setup Event Notification Subscription
    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 /event-subscriptions
    ASPSP Resource Server -> TPP: HTTP 201 (Created),  EventSubscriptionId

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

    alt 2a. ASPSP Sends Real Time Event Notification

    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
    end note

    opt If TPP requires full resource

    note right of TPP
    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

    end opt

    else 2b. TPP Requests Event Notifications

    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 Event Polling Service: Establish TLS 1.2 MA
    TPP -> ASPSP Event Polling Service: Acknowledge events
    ASPSP Event Polling Service -> TPP: HTTP 200 (Zero or more events)

    end

    note over TPP, ASPSP Event Polling 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 /event-subscriptions
    ASPSP Resource Server -> TPP: HTTP 200 (OK)
    else Update
    TPP -> ASPSP Resource Server: PUT /event-subscriptions/{EventSubscriptionId}
    ASPSP Resource Server -> TPP: HTTP 200 (OK)
    else Delete
    TPP -> ASPSP Resource Server: DELETE /event-subscriptions/{EventSubscriptionId}
    ASPSP Resource Server -> TPP: HTTP 204 (OK)
    end alt
    option footer=bar

### # Event Types and Extensibility

The specification defines a number of namespaced event types corresponding to individual event notifications.

ASPSPs may define their own custom Events (together with a corresponding namespaced event type) consistent with the principles and conventions outlined in the specification.

ASPSPs must document all supported events types on their developer documentation.

### # Event-Notification Backwards Compatibility

TPPs may have implemented the event-notification resource defined in v3.1 or v3.1.1 of the Event Notification API Specification. A TPP implementation limited to this resource would only be able to receive event-notifications for the `urn:uk:org:openbanking:events:resource-update` event. In order to receive backwards compatible v3.1.2 event-notifications, TPPs must restrict the events they receive to the `urn:uk:org:openbanking:events:resource-update` event using one of the following methods:

- Registering via the callback-url resource, implicitly limiting event types to `urn:uk:org:openbanking:events:resource-update`.
- Registering via the event-subscription resource with the Version set to 3.1.1, implicitly limiting events to `urn:uk:org:openbanking:events:resource-update`.
- Registering via the event-subscription resource. The Version element should be set to 3.1.2 and the EventTypes array limited to the value UK.OB.Resource-Update, explicitly limiting events to `urn:uk:org:openbanking:events:resource-update`.