Event Notifications v3.0.0

Owned by Nigel Somerfield
Jan 23, 2024
6 min read

Version Control

Overview

The Real Time Event Notification API Profile describes the flows common functionality for the Real Time Event Notification API, which allows API Providers to:

  • Notify a Third Party that an event has occurred.

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.

Implementation of the Real Time Event Notification API is mandatory for API Providers to implement and optional for Third Parties to utilise.

Basics

Overview

The steps and sequence diagram below provide a general outline of an event notification flow for all resources in the R/W APIs.

Steps

Step 1: Send Event Notification

  • When an event occurs on a resource that requires a notification, the API Provider identifies the callback-url associated with the Third Party owning the affected resource.

  • 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.

Sequence Diagram

Endpoints

An API Provider will send event notifications to a Third Party using the event-notification resource.

Endpoint list

Resource

HTTP Operation

Endpoint

Mandatory ?

Scope

Grant Type

Message Signing

Idempotency Key

Request Object

Response Object

Resource

HTTP Operation

Endpoint

Mandatory ?

Scope

Grant Type

Message Signing

Idempotency Key

Request Object

Response Object

event-notification

POST

POST /{callback-url}

Optional

n/a

n/a

Signed Request

No

NZEventNotification1

 

Notes:

  • A Third Party must make available an event notification endpoint (callback URL) to receive event notifications.

  • A Third Party must acknowledge an event notification with a 202 HTTP response and include the provided x-fapi-interaction-id.

POST /{callback-url}

The API endpoint allows the API Provider to send an event-notification resource to a Third Party. Third Parties must register their endpoint with the API Provider at the subscription endpoint.

Callback URL naming convention

The URL of the callback endpoint host by the Third Party is constrained to the following convention.

URL components:

  • Scheme: https

  • Host: Third Party DNS of endpoint, referred to as {tp-host}

  • Path prefix, including specification version number: /open-banking-nz/v3.0

  • Third Party suffix: Trailing path, referred to as {tp-path}

The above constraints mean the full URL is constructed:

https://{tp-host}/open-banking-nz/v3.0/{tp-path}

Example:

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

Transport Level Security

Third Party hosted endpoints must be protected using TLS 1.2 or higher, as per the FAPI R/W specification.

Third Party hosted endpoints must be protected using a network certificate issued by a Trust Anchor supported by the API Provider.

MA-TLS is not applicable to Third Party hosted endpoints.

Data Model

Event Notification - Request

The NZEventNotification1 object will be used for a call to:

  • POST /{callback-url}

Note, the NZEventNotification1 object is aligned with the Security Event Token (https://tools.ietf.org/html/rfc8417 ). It acts as a wrapper for events contained within the events claim.

UML Diagram

Notes

The rid, rty and rlk claims are prefixed with the API Centre namespace https://apicentre.paymentsnz.co.nz in the data model. The namespace has been removed from the diagram for clarity.

Data Dictionary

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

NZEventNotification1

NZEventNotification1

 

 

NZEventNotification1

 

 

iss

1..1

NZEventNotification1/iss

Issuer.

xs:anyURI

 

 

iat

1..1

NZEventNotification1/iat

Issued At.

xs:int

 

 

jti

1..1

NZEventNotification1/jti

JWT ID.

Max128Text

 

 

aud

1..1

NZEventNotification1/aud

Audience.

Max128Text

 

 

sub

1..1

NZEventNotification1/sub

Subject.

xs:anyURI

 

 

txn

1..1

NZEventNotification1/txn

Transaction Identifier.

Max128Text

 

 

toe

1..1

NZEventNotification1/toe

Time of Event.

xs:int

 

 

events

1..1

NZEventNotification1/events

Events.

NZEvent

 

 

urn:nz:co:paymentsnz:apicentre:events:account-access-consent-revoked

0..1

NZEventNotification1/events/urn:nz:co:paymentsnz:apicentre:events:account-access-consent-revoked

An event that indicates a account information access consent resource has had its authorisation revoked.

NZEventAccountAccessConsentRevoked

 

 

urn:nz:co:paymentsnz:apicentre:events:enduring-payment-consent-revoked

0..1

NZEventNotification1/events/urn:nz:co:paymentsnz:apicentre:events:enduring-payment-consent-authorization-revoked

An event that indicates a account information access consent resource has had its authorisation revoked.

NZEventEnduringPaymentConsentRevoked

 

 

NZEventSubject1

This section describes the NZEventSubject1 class which is used in the NZEventAccountAccessConsentRevoked and NZEventEnduringPaymentConsentRevoked classes.

UML Diagram

Notes

The rid, rty and rlk claims are prefixed with the API Centre namespace http://apicentre.paymentsnz.co.nz in the data model. The namespace has been removed from the diagram for clarity.

The array of resource links (http://apicentre.paymentsnz.co.nz/rlk) must contain links to all supported versions of the resource.

Data Dictionary

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

NZEventSubject1

 

 

 

NZEventSubject1

 

 

subject_type

1..1

NZEventSubject1/subject_type

Subject type for the updated resource.

Max128Text

http://apicentre.paymentsnz.co.nz/rid_http://apicentre.paymentsnz.co.nz/rty

 

http://apicentre.paymentsnz.co.nz/rid

1..1

NZEventSubject1/http://apicentre.paymentsnz.co.nz/rid

Resource Id for the updated resource.

Max128Text

 

 

http://apicentre.paymentsnz.co.nz/rty

1..1

NZEventSubject1/http://apicentre.paymentsnz.co.nz/rty

Resource Type for the updated resource.

Max128Text

 

 

http://apicentre.paymentsnz.co.nz/rlk

1..n

NZEventSubject1/http://apicentre.paymentsnz.co.nz/rlk

Resource links to other available versions of the resource.

NZEventLink1

 

 

version

1..1

NZEventSubject1/http://apicentre.paymentsnz.co.nz/rlk/version

Resource version.

Max10Text

 

 

link

1..1

NZEventSubject1/http://apicentre.paymentsnz.co.nz/rlk/link

Resource link.

xs:anyURI

 

 

NZEventAccountAccessConsentRevoked

This section describes the NZEventAccountAccessConsentRevoked class which is used in the NZEventNotification1 resource.

UML Diagram

Notes

For the NZEventAccountAccessConsentRevoked object:

Data Dictionary

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

urn:nz:co:paymentsnz:apicentre:events:account-access-consent-revoked

 

 

An event that indicates a (previously authorised) account information access consent has been revoked.

 

 

 

reason

0..1

urn:nz:co:paymentsnz:apicentre:events:account-access-consent-revoked/reason

Reason for the Consent Authorization Revoked event.

 

 

 

subject

1..1

urn:nz:co:paymentsnz:apicentre:events:account-access-consent-revoked/subject

The subject of the event.

NZEventSubject1

 

 

NZEventEnduringPaymentConsentRevoked

This section describes the NZEventEnduringPaymentConsentRevoked class which is used in the NZEventNotification1 resource.

UML Diagram

Notes

For the NZEventEnduringPaymentConsentRevoked object:

Data Dictionary

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

urn:nz:co:paymentsnz:apicentre:events:enduring-payment-consent-revoked

 

 

An event that indicates a consent resource has had its authorisation revoked.

NZEventEnduringPaymentConsentRevoked

 

 

reason

0..1

urn:nz:co:paymentsnz:apicentre:events:enduring-payment-consent-revoked/reason

Reason for the Consent Authorization Revoked event.

 

NZExternalEventConsentAuthorizationRevokedReason1Code

 

subject

0..1

urn:nz:co:paymentsnz:apicentre:events:enduring-payment-consent-revoked/subject

The subject of the event.

NZEventSubject1

 

 

Event Notification Retry Policy

API Provider

An API Provider's Event Notification Retry Policy defines behaviour when an event notification is unacknowledged or the API Provider receives a 5xx error.

  • An Event Notification Retry Policy must define an Exponential Backoff Policy to calculate the Retry Time Interval.

  • An Event Notification Retry Policy must define the Maximum Number of Retries an API Provider will make before declaring the Third Party Event Notification endpoint unresponsive and ceasing further attempts.

  • An Event Notification Retry Policy must define the Maximum Time Interval for Retries, after which an API Provider will declare the Third Party Event Notification endpoint unresponsive and cease further attempts.

Third Party

A Third Party may make GET requests for its resources if its /{callback-url} endpoint was unavailable for the Maximum Time Interval for Retries, as defined in an API Provider's Event Notification Retry Policy.

Errors

The following error scenarios can occur during event notification delivery:

  • POST /{callback-url}

Scenario

HTTP Response code

Notes

Scenario

HTTP Response code

Notes

An error was encountered at the third party while processing an event notification. The API provider may retry the request.

400 Bad Request

Examples include: expired SET token (iat is too far in the past to be meaningful, or exp was included and is in the past), invalid SET structure (missing or unspecified members, values do not match expected type), problem validating SET token signature.
When retrying, the token may be re-issued, but must not change values pertinent to the event: toe, txn, and events members must not be changed

The third party is experiencing problems with the callback endpoint. The API provider may retry the request unmodified.

500 Internal Service Error

 

The API provider does not receive any HTTP response within a pre-determined timeout window (specified by API provider)

n/a

The API provider will enact their retry policy

401, 403 are not relevant since no bearer authentication token are not supplied in the callback request. Content-Type header is determined by SET token RFC 8417 to application/secevent+jwt and content negotiation is not applicable; a failure to use correct media type results in 400 Bad Request (rather than 406/415). No body is returned in the success response.

Usage Examples

Note: the following non-normative examples are encoded with PS256 algorithm using the following key:

{ "e":"AQAB", "kid":"HtpA0hf-eAp4aSSc1grpa6yIlqoPAQNw0j5hB6rWMZY", "kty":"RSA", "n":"z6SOiYPPU45domyKots4A53ZVaMiZ5MQhiXbV5rIXy9iO8nwRzcJr3pJjWSwukBYI4LtPUziYFh1xd5xkw5gHe7dLaqmPhm4CnzqCNgFOxDe_YHdLaXj3j8V7xa0-uYX21nhwGSINBB-mNwXgBeR2017ohWzfWUjy8RsJO23txP4Xt3J8rOyQEdpt-kHDHHqTl5rdhEnHwnAY3x0sCaW0qva3dlwzotWS7BgEvWAH6dhoaW51ziSKcwg2_YRUySsyfFZnjwpRyi3N1hThRXe7JUCLBugQZln1cYFT7072AaFBPxxuEhV0z4LDNmbDehkaEi8k42I7AjsBfDV9XsvyiVWfAdAhx1JmsHxi8ycontREUfs1q1QzqO1All_7qHW19AWkUajoZTZIp3P-rCt5uwbCOENOO9ACBAhCrPilCGB8GVtteuVBp-3bDZsM22XKiYmrpV084gsCw6XOJqOCCAUdmSWJ3YVM7mfB1F9F-xKyB3NHcsHImdNRXScHwO4DrVRq5jp-Gc3pc_D7cfnA3xAAfm1VxddGh1_BfGQoXJXl3mgpMR-LhMOXTk7WwChXCdrHanhQjY1xwM-JjMGxjLTyklVzbo8Q9v063tTunrQ1Wn8fFliBRdcq46ImpjSoldu9Q-ZRYLFSb0uYD3_G13X2gOHZQeT1NEVOp2a9tc" }

For the allowed algorithms for signing SETs, refer to the Security Profile.

Send Event Notification - Account Access Consent Authorisation Revoked

In case of Account Information Access/Authorization revocation, the state of the Consent resource is updated to Revoked. This triggers only one event for the underlying consent resource:

  • Account Access Consent

POST Event Notification Request

POST /{callback-url} HTTP/1.1 x-fapi-interaction-id: 2498371e-a900-4434-81ff-37c9cc5b77fc Content-Type: application/secevent+jwt eyJhbGciOiJQUzI1NiIsImtpZCI6Ikh0cEEwaGYtZUFwNGFTU2MxZ3JwYTZ5SWxxb1BBUU53MGo1aEI2 cldNWlkiLCJ0eXAiOiJzZWNldmVudCtqd3QifQ.eyJhdWQiOiI3dW14NW5UUjMzODExUXlRZmkiLCJld mVudHMiOnsidXJuOm56OmNvOnBheW1lbnRzbno6YXBpY2VudHJlOmV2ZW50czphY2NvdW50LWFjY2Vzc y1jb25zZW50LXJldm9rZWQiOnsic3ViamVjdCI6eyJodHRwOi8vYXBpY2VudHJlLnBheW1lbnRzbnouY 28ubnovcmlkIjoiYWFjLTEyMzQtMDA3IiwiaHR0cDovL2FwaWNlbnRyZS5wYXltZW50c256LmNvLm56L 3JsayI6W3sibGluayI6Imh0dHBzOi8vZXhhbXBsZWJhbmsuY28ubnovYXBpL29wZW4tYmFua2luZy1ue i92My4wL2FjY291bnQtYWNjZXNzLWNvbnNlbnRzL2FhYy0xMjM0LTAwNyIsInZlcnNpb24iOiJ2My4wI n1dLCJodHRwOi8vYXBpY2VudHJlLnBheW1lbnRzbnouY28ubnovcnR5IjoiYWNjb3VudC1hY2Nlc3MtY 29uc2VudHMiLCJzdWJqZWN0X3R5cGUiOiJodHRwOi8vYXBpY2VudHJlLnBheW1lbnRzbnouY28ubnovc mlkX2h0dHA6Ly9hcGljZW50cmUucGF5bWVudHNuei5jby5uei9ydHkifX19LCJpYXQiOjE2NzM0NzI4N DQsImlzcyI6Imh0dHBzOi8vZXhhbXBsZWJhbmsuY28ubnoiLCJqdGkiOiJhZTE5ZjU5NS1hMGY4LTRkY mYtOGFkNy01YTU5NGJmOTE2NzQiLCJzdWIiOiJodHRwczovL2V4YW1wbGViYW5rLmNvLm56L2FwaS9vc GVuLWJhbmtpbmctbnovdjMuMC9hY2NvdW50LWFjY2Vzcy1jb25zZW50cy9hYWMtMTIzNC0wMDciLCJ0b 2UiOjE2NzM0NzI4MzksInR4biI6ImExNjZlNTZkLWMxNzgtNDNjNi05YzBhLTExNGJmNTQ3YzhkZiJ9. cna7Am_nJXlfMjjL0BF9WjVc0nYOdpyaSzkubhZv5IzSvEyWih3-xBSRnzzmTy1EVFscx_B62_yQFlMQ yf8Rjphfa5Gb5UK78IlWli6czdMRgv3Ichua-3Hl4SHZmX6zuy3jK-6dl4iIgdwrnVVOnT5YrdCUv1ch rZc_bd-tTxBJx5VL_c6jlb0xOrDgNK00fOsS6GJ7p1VSqDbCmkAz8WBmNiEZYk44LON7HklPHk6zOWlI 5kEzc2nvAURXTmqAscrhP2d88BzZCAkHQ9Wf36O_EupSU9Me9GQpDPRWh3Q7GR76tw7tLFpBQ8pYAzHE qlJQLDaTojLQEIgiOTTuadnyMcSZ-lgFLy-9Ze7CxCQST4MtEEM9BOqAccExl8xkiCMPeZQBskhd0fUk Ymwf4S_MIFh-MfCuKQcV5ASQVYOOkftyhi8lfjsdkU9heMqLSuuw5Jr-wOPD9yuGpPhakg08sIl11Owj NtgSXf2W1UuPzYgmI_AHb8cS-Nd3TYl4jUXyTVwBdBJQOA6-ZFJlcBEZCwFgZNaClHy2LQrI09aUuuTJ kx7L24tHHJWyQtikQiP4hxHpW2xpMdO_KdrE2PfcWHdx25DbNa94assk2D5S7JHbMMGqfjV7g1objpPv MghiiIDKBleruEPYl69OW0ebypyQfqYVFTIkt0U7Q0I

Decoded JWT Body - Event Notification Payload

{ "aud": "7umx5nTR33811QyQfi", "events": { "urn:nz:co:paymentsnz:apicentre:events:account-access-consent-revoked": { "subject": { "http://apicentre.paymentsnz.co.nz/rid": "aac-1234-007", "http://apicentre.paymentsnz.co.nz/rlk": [{ "link": "https://examplebank.co.nz/api/open-banking-nz/v3.0/account-access-consents/aac-1234-007", "version": "v3.0" }], "http://apicentre.paymentsnz.co.nz/rty": "account-access-consents", "subject_type": "http://apicentre.paymentsnz.co.nz/rid_http://apicentre.paymentsnz.co.nz/rty" } } }, "iat": 1673472844, "iss": "https://examplebank.co.nz", "jti": "ae19f595-a0f8-4dbf-8ad7-5a594bf91674", "sub": "https://examplebank.co.nz/api/open-banking-nz/v3.0/account-access-consents/aac-1234-007", "toe": 1673472839, "txn": "a166e56d-c178-43c6-9c0a-114bf547c8df" }

POST Event Notification Response

Send Event Notification - Enduring Payment Consent Authorisation Revoked

In case of Enduring Payment Consent authorisation revocation, the state of the Consent resource is updated to Revoked. This triggers only one event for the underlying consent resource:

  • Enduring Payment Consent

POST Event Notification Request

Decoded JWT Body - Event Notification Payload

POST Event Notification Response