Version Control

Overview

The Event Notification Subscription API Profile describes the flows and common functionality for the Event Notification Subscription API, which allows a Third Party to:

• Register an event subscription with an API Provider to subscribe to event notifications.

  • A subscription can enable real time event notifications via a HTTP callback from the API Provider

• Specify a list of event types to be notified on.

• Optionally read, update or delete a registered event subscription.

This profile should be read in conjunction with a compatible Read/Write Data API Profile, a compatible Event Notification API Profile and compatible individual resources.

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 Subscription

• This flow begins with a Third Party creating an event-subscription resource with an API Provider.

Step 2: Retrieve/Update/Delete Event Notification Subscription

• The Third Party may optionally read/update/delete the event-subscription resource.

Sequence Diagram

Open

Subscriptions for Real Time Event Notifications

API Providers may choose to offer Real Time Notifications. Third Parties will subscribe to the different notification event types using the event-subscription resource.

Real Time Event Notifications

Third Parties must register an event subscription with a CallbackUrl for Third Party hosted services to receive real time event notifications from an API Provider (providing an API Provider supports this functionality).

The CallbackUrl must end with the Event Notification API specification version number, followed by a path specified by the Third Party. This is referred to as the {callback-url}. See https://paymentsnz.atlassian.net/wiki/spaces/PaymentsNZAPIStandards/pages/1720811582/Event+Notifications+v3.0.0#Callback-URL-naming-convention for details.

For example:

URL: https://api.thirdparty.co.nz/open-banking-nz/v3.0/event-notifications

Aggregated Polling

Aggregated polling is not supported in this version of the standard.

Release Management

This section overviews the release management and versioning strategy for the Event Notification API.

Event-Subscription Resource

Third Parties must register for event-subscriptions with the version of Event Notification API they have implemented. The version field of the event-subscription resource is used for this purpose.

POST

• A Third Party must only create an event-subscription on one version

GET

• A Third Party must not access a event-subscription on an older version, via the EventSubscriptionId for an event-subscription created in a newer version.

  • E.g., a event-subscription created in v4, accessed via v3.

• An API Provider must allow an event-subscription resource to be accessed in a newer version.

• An API Provider must ensure event-subscription fields are unchanged when accessed in a different version.

PUT

• A Third Party must not update an event-subscription on an older version via a EventSubscriptionId created in a newer version.

  • E.g., A event-subscription is created in v4, and a PUT request on v3.

• An API Provider must support updating an event-subscription from a previous version via a EventSubscriptionId created in a newer version.

  • E.g., A event-subscription is created in v3, and a PUT request on v4.

DELETE

• A Third Party must not delete an event-subscription on an older version via a EventSubscriptionId created in a newer version.

  • E.g. An event-subscription is created in v4, and request DELETE on v3.

• An API Provider must support deleting an event-subscription from a previous version via a EventSubscriptionId created in a newer version.

  • E.g., An event-subscription is created in v3, and request DELETE on v4.

Event-Subscription per Third Party

An API Provider will maintain at most, a single event-subscription resource per Third Party.

Event Subscription Resource Overview

The Event Subscription resource is used by a Third Party to subscribe to events with an API Provider.

This resource description should be read in conjunction with a compatible Event Notification Subscription Profile.

Endpoints

A Third Party will set up and maintain its event subscription details (URL, event types and version number) using the event-subscription resource.

POST /event-subscriptions

The API endpoint allows the Third Party to ask an API Provider to create a new event-subscription resource.

• The POST action allows the Third Party to register an event subscription for a Third Party to access event notifications.

• The API Provider creates the event-subscription resource and responds with a unique EventSubscriptionId to refer to the resource.

• An API Provider must respond with a 409 error if an event-subscription exists for that Third Party.

GET /event-subscriptions

The API endpoint allows the Third Party to ask an API Provider to retrieve its event-subscription resource.

• The API Provider retrieves the event-subscription resource and responds with the resource.

PUT /event-subscriptions/{EventSubscriptionId}

The API endpoint allows the Third Party to ask an API Provider to update an event-subscription resource.

• The PUT action allows the Third Party to update an event subscription for a Third Party to access event notifications.

• The API Provider updates the event-subscription resource and responds with the updated resource.

DELETE /event-subscriptions/{EventSubscriptionId}

The API endpoint allows the Third Party to ask an API Provider to delete an event-subscription resource.

• The API Provider deletes the event-subscription resource.

Data Model

Event Subscription - Request

The NZEventSubscription1 object will be used for the call to:

• POST /{callback-url}

UML Diagram

Open

Notes

For the NZEventSubscription1 object:

• Third Party must provide CallbackUrl, when subscribing for events.

• Third Party must provide the Version of Resources, for which they want to subscribe the events for. E.g. if supplied with value "3.0", Third Party indicates the subscription for the change in state of resources created in v3.0 version

• EventTypes usage:

  • Third Parties must provide a list of event types to subscribe to specific events.

Data Dictionary

Event Subscription - Response

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

• POST /event-subscriptions

• PUT /event-subscriptions/{EventSubscriptionId}

UML

Data Dictionary

Event Subscriptions - Response

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

• GET /event-subscriptions

UML

Data Dictionary

Errors

The following error scenarios can occur during event subscription creation or modification:

• POST /event-subscriptions)

• PUT /event-subscriptions/{EventSubscriptionId}

The following error scenarios can occur during event subscription retrieval and deletion:

• GET /event-subscriptions

• DELETE /event-subscriptions/{EventSubscriptionId}

Usage Examples

Create Event Subscription

POST Event Subscription Request

POST Event Subscription Response

Get Event Subscriptions

GET Event Subscription Request

GET Event Subscription Response