Version Control

Overview

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

The Event Notification Subscription API Profile provides the mechanism for Third Parties to register for event notifications.

The Event Notification Subscription API allows Third Parties to register to receive all or specific event types via the Real Time Event Notification 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 mandatory for API Providers to implement and optional for Third Parties to utilise.

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 RFC 8417. An event notification is structured as a JWT, indicating an event has occurred through a set of claims.

A resource-update event (urn:nz:co:paymentsnz:apicentre: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.

At-least-once delivery

Notification delivery may fail. An API Provider must implement a retry policy, where the API provider notification service attempts re-delivery of a notification. This may result in the Third Party seeing the notification more than once, and the Third Party must identify this as re-delivery, rather than a new notification.

SET Aggregation Not Included

In contrast with the upstream UK standard, aggregated polling of Security Event Tokens is not supported. This simplifies the implementation for API providers and Third Parties for the v3.0 standards.

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 Third Party registration for event notifications is performed using the Event Notification Subscription API.

Steps

Step 1: Setup Event Notification Subscription

• This flow begins with a Third Party creating an event-subscription resource with an API Provider. This must include a callback URL, and a series of event types.

Step 2: Deliver Event Notification

• An event corresponding to one of an API Provider's event types occurs on a resource.

• A Third Party must have provided a callback URL with the event-subscription resource in order to receive the real time event notification.

• The API Provider sends a signed event notification to the callback URL, detailing the nature of the event and identifying the affected resource.

• The Third Party may optionally initiate a client credential grant to retrieve the resource using the details contained in the event notification.

• The API provider must have a retry policy for failed delivery of notifications. This may result in the same notification being delivered more than once.

Step 3: Retrieve/Update/Delete Event Notification Subscription

• A Third Party may Retrieve/Update/Delete the event notification subscription

Sequence diagram

participant Third Party
participant "API Provider\nAuthorisation Server" as Authz
participant "API Provider\nResource Server" as Resource
participant "API Provider\nNotification Service" as Notification

note over Third Party, Notification
Step 1: Setup Event Notification Subscription
end note

Third Party <-> Authz: Establish TLS 1.2/1.3 MA
Third Party -> Authz: Initiate Client Credentials Grant
Authz -> Third Party: access-token
Third Party <-> Resource: Establish TLS 1.2/1.3 MA
Third Party -> Resource: POST /event-subscriptions, callback-url, event types
Resource -> Third Party: HTTP 201 (Created),  EventSubscriptionId

note over Third Party, Notification
 Step 2: Deliver Event Notification
end note


alt 2. API Provider Sends Real Time Event Notification

note left of Notification
- Create EventNotification
- Sign EventNotification
end note

loop Retry Until Successful (as per retry policy)
Notification -> Third Party: POST /{callback-url}, EventNotification, signature
alt success
Third Party -> Notification: HTTP 202 Accepted
else failure
Third Party -> Notification: HTTP 500/400
else timeout
Third Party -->x Notification: No response
end alt
end loop

note right of Third Party
Third Party verifies signature
end note

opt If Third Party requires full resource

note right of Third Party
URL for resource contained in the
EventNotification rlk (resource links) claim
end note

Third Party <-> Authz: Establish TLS 1.2/1.3 MA
Third Party -> Authz: Initiate Client Credentials Grant
Authz -> Third Party: access-token

Third Party <-> Resource: Establish TLS 1.2/1.3 MA
Third Party -> Resource: GET Resource
Resource -> Third Party: HTTP 200 (OK),  Resource

end opt

end

note over Third Party, Notification
Step 3: Retrieve/Update/Delete Event Notification Configuration
end note

Third Party <-> Authz: Establish TLS 1.2/1.3 MA
Third Party -> Authz: Initiate Client Credentials Grant
Authz -> Third Party: access-token
Third Party <-> Resource: Establish TLS 1.2/1.3 MA
alt Retrive
Third Party -> Resource: GET /event-subscriptions
Resource -> Third Party: HTTP 200 (OK)
else Update
Third Party -> Resource: PUT /event-subscriptions/{EventSubscriptionId}
Resource -> Third Party: HTTP 200 (OK)
else Delete
Third Party -> Resource: DELETE /event-subscriptions/{EventSubscriptionId}
Resource -> Third Party: HTTP 204 (OK)
end alt

Event Types and Extensibility

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

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

API Providers must document all supported events types on their developer documentation.

Endpoints

The API endpoints for these resources, and their mandatory or optional status are given below.

Notes

Definitions for Mandatory and Optional are given in the NZ Banking Data API Specification.

If Third Party providers use event-subscription, the implementation of event-notification becomes mandatory.

OpenAPI Specifications

The OpenAPI Specification for the Event Notification APIs can be downloaded from https://github.com/PaymentsNZ/API-Event-Notification