Event Notification API v3.0.1

Owned by Nigel Somerfield
Last updated: Sept 04, 2024
4 min read

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.

Resource

Endpoints

Mandatory?

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