Event Notification API v3.0.1
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
Ā
Ā
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.
Resource | Endpoints | Mandatory? |
---|---|---|
event-subscription | POST /event-subscriptions | Mandatory |
event-subscription | GET /event-subscriptions | Mandatory |
event-subscription | PUT /event-subscriptions/{EventSubscriptionId} | Mandatory |
event-subscription | DELETE /event-subscriptions/{EventSubscriptionId} | Mandatory |
event-notification | POST /{CallbackUrl} | Optional (Third Party) |
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