Introduction

Event Notifications is a new feature that is specific to version 3.0 and later of the API Centre standards. A Third Party subscribes to types of notifications they wish to receive which are generated and sent by the API Provider when the related event occurs. The API Provider will send the notifications to the endpoint specified in the subscription created by the Third Party.

To reduce complexity, only a single subscription per Third Party is maintained at the API Provider, however a single subscription can include multiple notification types. Third Parties may update their subscription at any time, including removing (deleting) it.

Glossary

The following terms are used in this explainer:

Prerequisites

Before making use of Event Notifications API, a Third Party must have:

• A bilateral agreement in place with an API Provider

• Established connectivity with the API Provider

• Deployed an endpoint that is capable of receiving and processing Event Notifications

  • The endpoint URI must match the Event Notification requirements

Version applicability

As event notifications is new in v3.0, notifications are currently only supported for resources created using v3.0 API standards. This is because applying event notifications to previous versions would mean:

1. Previous API Provider implementations (prior to v3.0) must add new functionality to continue to be compliant, and

2. Standards versions would now need to include forward-compatibility (as well as backwards-compatibility) considerations, which may detract from the ability to add new features

The following table summarises the applicability of Event Notifications to the resource version:

Operation of event notifications

Event notifications in v3.0 are functionally quite simple, in order to reduce the complexity for implementation. A Third Party creates a subscription via the API for any of the two currently available event notification types, and when a change occurs to a resource that matches the event notification type the API Provider sends the event notification to the Third Party endpoint.

Scopes

Event Notifications are created using access tokens that are issued through client credentials authorisation grant flow. To create subscriptions the Third Party uses the following scopes, supplied in the authorisation request:

• payments for subscriptions that relate to Payment Initiation API resources

• accounts for subscriptions that relate to Account Information API resources

Subscribing to events

To create a subscription, an API request is made to POST /event-subscriptions, including three key pieces of information:

• CallbackUrl - the endpoint the Third Party hosts that will receive event notifications that are sent by the API Provider.

• Version - the resource version for which event notifications will be generated. In v3.0, only '3.0' is supported, which means that only events relating to resources created using v3.0 will be sent to the Third Party.

• EventTypes - a list of requested event types that the Third Party would like to receive notifications for. In v3.0, there are two types that are mandatory for API Providers to support:

  • Revocation of account access consents

  • Revocation of enduring payment consents

Note: API providers may extend with custom event types, however these must be namespaced in a manner that avoids collision with API Centre event types.

If a subscription is successfully created, then the API request is reflected back to the Third Party with the addition of:

• EventSubscriptionId - The ID of the created subscription resource. This is used in subsequent update or removal requests.

In v3.0, only a single subscription per Third Party / API Provider combination is supported, and there will be only a single subscription version.

In future versions of the standard, it may be possible to create one or more subscriptions in those versions or subscribe to multiple notifications for multiple resource versions. A Third Party could have subscriptions that span multiple subscription versions and/or multiple resource versions within a subscription. This could enable such use-cases as:

• Subscriptions for different event types or multiple resource versions managed independently

• Different resource versions of same event type in separate subscriptions

• Subscriptions for different event types sent to different Callback URL using separate subscriptions

Subscription example

Examples of the event subscription can be found here. Below is some expanded guidance on key aspects of an event subscription request:

Third Party endpoint that will receive event notifications:

The resource version for which specified event notifications will be generated. Note that for this example the Third Party will receive notifications for resources that were created using version 3.0 APIs. If the subscription creation request succeeds, this is the subscribed version:

The following shows an example of both supported event notification types being requested:

Receive Notifications

Given a subscription for event notifications has been successfully created, a Third Party can now receive notifications for events that relate to the types and resource version specified in the subscription. These will be delivered to the specified callback URL, via POST /${CallbackUrl}, where CallbackUrl was specified in the request.

Notification example

Examples of notifications can be found here. Below is some expanded guidance on the notification that will be sent to the API Provider.

The events object contains the event notification payload, identified by the URN relating to one of those requested in the subscription:

The events specify the subject which contains:

• the identifier of the resource that changed,

• one or more link objects to where the resource and resource version that can be retrieved

• the type of the resource for which the event was specified

• the subject type, which is an amalgamation of member names for resource ID and resource type

These are shown in the example subject contents below:

Multiple link example

If an API Provider has multiple versions of the API where the resource can be retrieved, these must be specified in the links array;

Retrieve resource

To retrieve the updated resource, a Third Party makes a GET request to the endpoint specified in the link array. For example

Manage subscriptions

A Third Party may optionally choose to update, retrieve or remove their subscriptions.

Third Party can update (replace) their event notification subscription supplying an updated subscription request via PUT /event-subscriptions/{EventSubscriptionId} request. Since the update/change mechanism is via HTTP PUT, the subscription is replaced in its entirety with the supplied resource.

Third Parties delete a subscription via a DELETE /event-subscriptions/{EventSubscriptionId} request

A Third Party can retrieve their subscriptions via a GET /event-subscriptions request. Because only a single subscription per Third Party / API Provider is currently supported this will return a single resource.