Skip to end of metadata
Go to start of metadata

You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 13 Next »

1. Overview

The Event Notification resource is used by a ASPSP to notify a TPP of an event.

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

2. Endpoints

An ASPSP will send event notifications to a TPP using the event-notification resource.

S. No.

Resource

HTTP Operation

Endpoint

Mandatory ?

Scope

Grant Type

Message Signing

Idempotency Key

Request Object

Response Object

2.1

event- notification

POST

POST / event- notifications

Optional

n/a

n/a

No

No

OBEventNotification

Notes:

  • A TPP must make available an event notification endpoint to receive event notifications.

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

2.1 POST/event-notifications

The API endpoint allows the ASPSP to send an event-notification resource to a TPP.

2.2 Transport Level Security

TPP hosted endpoints must be protected using TLS 1.2, as per the FAPI R/W specification.

TPP hosted endpoints must be protected using a network certificate issued by a Trust Anchor supported by the ASPSP.

MA-TLS is not applicable to TPP hosted endpoints.

3. Data Model

3.1 Event Notification - Request

The OBEventNotification object will be used for a call to:

  • POST /event-notifications

Note, the OBEventNotification 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

 3.1.1 UML Diagram

3.1.2 Notes

The rid, rty and rlk claims are prefixed with the OB namespace http://openbanking.org.bh in the data model. The namespace has been removed from the diagram for clarity.

3.1.3 Data Dictionary

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

OBEventNotification

OBEventNotification2

 

 

OBEventNotification

 

 

iss

1..1

OBEventNotification/iss

Issuer.

String

 

 

iat

1..1

OBEventNotification/iat

Issued At.

Number

 

 

jti

1..1

OBEventNotification/jti

JWT ID.

String

 

 

aud

1..1

OBEventNotification/aud

Audience.

String

 

 

sub

1..1

OBEventNotification/sub

Subject.

String : URI

 

 

txn

1..1

OBEventNotification/txn

Transaction Identifier.

String

 

 

toe

1..1

OBEventNotification/toe

Time of Event.

Number

 

 

events

1..1

OBEventNotification/events

Events.

OBEvent

 

 

urn:bh:org:cbb_openbanking:events:resource-update 

0..1

OBEventNotification/events/ urn:bh:org:cbb_openbanking:events:resource-update 

Resource-Update Event.

OBEventResourceUpdate

 

 

urn:bh:org:cbb_openbanking:events:account-access-consent-linked-account-update 

0..1

OBEventNotification/events/ urn:bh:org:cbb_openbanking:events:account-access-consent-linked-account-update

An event that indicates an account linked to a consent has move in/out of scope of the consent.

OBEventAccountAccessConsentLinkedAccountUpdate

 

 

urn:bh:org:cbb_openbanking:events:consent-authorization-revoked 

0..1

OBEventNotification/events/ urn:bh:org:cbb_openbanking:events:consent-authorization-revoked

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

OBEventConsentAuthorizationRevoked

 

 

3.2  OBEventSubject

This section describes the OBEventSubject class which is used in the OBEventResourceUpdate, OBEventConsentAuthorizationRevoked and OBEventAccountAccessConsentLinkedAccountUpdateclasses.

3.2.1 UML Diagram

 

3.2.2 Notes

  • The rid, rty and rlk claims are prefixed with the OB namespace http://openbanking.org.bh in the data model. The namespace has been removed from the diagram for clarity.

  • The array of resource links (http://openbanking.org.bh/rlk) must contain links to all supported versions of the resource.

 3.2.3 Data Dictionary

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

OBEventSubject

 

 

 

OBEventSubject

 

 

subject_type

1..1

OBEventSubject/subject_type

Subject type for the updated resource.

String

http://openbanking.org.bh/rid_http://openbanking.org.bh/rty

 

http://openbanking.org.bh/rid

1..1

OBEventSubject/http://openbanking.org.bh/rid

Resource Id for the updated resource.

String

 

 

http://openbanking.org.bh/rty

1..1

OBEventSubject/http://openbanking.org.bh/rty

Resource Type for the updated resource.

String

 

 

http://openbanking.org.bh/rlk

1..n

OBEventSubject/http://openbanking.org.bh/rlk

Resource links to other available versions of the resource.

OBEventSubject/http://openbanking.org.bh/rlk

 

 

version

1..1

OBEventSubject/http://openbanking.org.bh/rlk/version

Resource version.

String

 

 

link

1..1

OBEventSubject/http://openbanking.org.bh/rlk/link

Resource link.

String

 

 

3.3  OBEventResourceUpdate

This section describes the OBEventResourceUpdate class which is used in the OBEventNotification resource.

3.3.1 UML Diagram

 3.3.2 Notes

  • The rid, rty and rlk claims are prefixed with the OB namespace http://openbanking.org.bh in the data model. The namespace has been removed from the diagram for clarity.

  • The array of resource links (http://openbanking.org.bh/rlk) must contain links to all supported versions of the resource.

3.3.3 Data Dictionary

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

urn:bh:org:cbb_openbanking:events:resource-update

 

 

An event that indicates a resource has been updated.

OBEventResourceUpdate

 

 

subject

1..1

urn:bh:org:cbb_openbanking:events:resource-update /subject

The subject of the event.

OBEventSubject

 

 

3.4  OBEventConsentAuthorizationRevoked

 This section describes the OBEventConsentAuthorizationRevoked class which is used in the OBEventNotification resource

3.4.1 UML Diagram

3.4.2 Notes

For the OBEventConsentAuthorizationRevoked object:

  • The subject claim must be populated if the Event Notification does not include a urn:bh:org:cbb_openbanking:events:resource-update event

3.4.3 Data Dictionary 

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

urn:bh:org:cbb_openbanking:events:consent-authorization-revoked

 

 

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

OBEventConsentAuthorizationRevoked

 

 

reason

0..1

urn:bh:org:cbb_openbanking:events:consent-authorization-revoked/reason

Reason for the Consent Authorization Revoked event.

String

 

 

subject

0..1

urn:uk:org:openbanking:events:consent-authorization-revoked/subject

The subject of the event.

OBEventSubject

 

 

 

3.5 OBEventAccountAccessConsentLinkedAccountUpdate

This section describes the OBEventAccountAccessConsentLinkedAccountUpdate class which is used in the OBEventNotification resource.

3.5.1 UML Diagram

3.5.2 Notes

For the OBEventAccountAccessConsentLinkedAccountUpdate object:

3.5.3 Data Dictionary

Name

Occurrence

XPath

Enhanced Definition

Class

Codes

Pattern

urn:bh:org:cbb_openbanking:events:account-access-consent-linked-account-update

 

 

An event that indicates an account linked to a consent has move in/out of scope of the consent.

OBEventAccountAccessConsentLinkedAccountUpdate

 

 

reason

0..1

urn:bh:org:cbb_openbanking:events:account-access-consent-linked-account-update/reason

Reason for the Account Access Consent Linked Account Update event.

String

 

 

subject

1..1

urn:bh:org:cbb_openbanking:events:account-access-consent-linked-account-update/subject

The subject of the event.

OBEventSubject

 

 

3.6  Event Notification Retry Policy

3.6.1 ASPSP

An ASPSP's Event Notification Retry Policy defines behaviour when an event notification is unacknowledged or the ASPSP 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 ASPSP will make before declaring the TPP Event Notification endpoint unresponsive and ceasing further attempts.

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

3.6.2 TPP

A TPP may make GET requests for its resources if its /event-notifications endpoint was unavailable for the Maximum Time Interval for Retries, as defined in an ASPSP's Event Notification Retry Policy.

4. Usage Examples

4.1 Send Event Notification - Resource Update

4.1.1 POST Event Notification Request

POST /event-notifications HTTP/1.1

x-fapi-interaction-id: 14ba1762-a316-4a87-8d6e-5bfbefaf01d7

Content-Type: application/jwt

 eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGViYW5rLmNvbS8iLCJpYXQiOiIxNTE2MjM5MDIyIiwianRpIjoiYjQ2MGEwN2MtNDk2Mi00M2QxLTg1ZWUtOWRjMTBmYmI4ZjZjIiwic3ViIjoiaHR0cHM6Ly9leGFtcGxlYmFuay5jb20vYXBpL29wZW4tYmFua2luZy92My4wL3Bpc3AvZG9tZXN0aWMtcGF5bWVudHMvcG10LTcyOTAtMDAzIiwiYXVkIjoiN3VteDVuVFIzMzgxMVF5UWZpIiwiZXZlbnRzIjp7InVybjp1azpvcmc6b3BlbmJhbmtpbmc6ZXZlbnRzOnJlc291cmNlLXVwZGF0ZSI6eyJzdWJqZWN0Ijp7InN1YmplY3RfdHlwZSI6Imh0dHA6Ly9vcGVuYmFua2luZy5vcmcudWsvcmlkX2h0dHA6Ly9vcGVuYmFua2luZy5vcmcudWsvcnR5IiwiaHR0cDovL29wZW5iYW5raW5nLm9yZy51ay9yaWQiOiJwbXQtNzI5MC0wMDMiLCJodHRwOi8vb3BlbmJhbmtpbmcub3JnLnVrL3J0eSI6ImRvbWVzdGljLXBheW1lbnQiLCJodHRwOi8vb3BlbmJhbmtpbmcub3JnLnVrL3JsayI6W3sidmVyc2lvbiI6InYzLjAiLCJsaW5rIjoiaHR0cHM6Ly9leGFtcGxlYmFuay5jb20vYXBpL29wZW4tYmFua2luZy92My4wL3Bpc3AvZG9tZXN0aWMtcGF5bWVudHMvcG10LTcyOTAtMDAzIn0seyJ2ZXJzaW9uIjoidjEuMSIsImxpbmsiOiJodHRwczovL2V4YW1wbGViYW5rLmNvbS9hcGkvb3Blbi1iYW5raW5nL3YxLjEvcGF5bWVudHMvcG10LTcyOTAtMDAzIn1dfX19LCJ0eG4iOiJkZmM1MTYyOC0zNDc5LTRiODEtYWQ2MC0yMTBiNDNkMDIzMDYiLCJ0b2UiOiIxNTE2MjM5MDIyIn0.-coUJsJVycbZufiWHi71TIQsCjP4gj9uZ4FOsNEysZ4

Decoded JWT Body - Event Notification Payload

{   "iss": "https://examplebank.com/",   "iat": 1516239022,   "jti": "b460a07c-4962-43d1-85ee-9dc10fbb8f6c",   "sub": "https://examplebank.com/api/open-banking/v3.1/aisp/account-access-consents/aac-1234-007",   "aud": "7umx5nTR33811QyQfi",   "events": {     "urn:bh:org:openbanking:events:resource-update": {       "subject": {         "subject_type": "http://openbanking.org.bh/rid_http://openbanking.org.bh/rty",         "http://openbanking.org.bh/rid": "aac-1234-007",         "http://openbanking.org.bh/rty": "account-access-consent",         "http://openbanking.org.bh/rlk": [{             "version": "v3.1",             "link": "https://examplebank.com/api/open-banking/v3.1/aisp/account-access-consents/aac-1234-007"           }         ]       }     }   },   "txn": "dfc51628-3479-4b81-ad60-210b43d02306",   "toe": 1516239022 }

4.1.2 POST Event Notification Response

HTTP/1.1 202 Accepted x-fapi-interaction-id: 14ba1762-a316-4a87-8d6e-5bfbefaf01d7 

 4.2  Send Event Notification - AIS Consent Authorisation Revoked

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

  •    consent-authorization-revoked

4.2.1 POST Event Notification Request

POST /event-notifications HTTP/1.1 x-fapi-interaction-id: db54268f-2cc7-47e3-bf3c-4b5a7d08a614 Content-Type: application/jwt   eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGViYW5rLmNvbS8iLCJpYXQiOjE1MTYyMzkwMjIsImp0aSI6ImI0NjBhMDdjLTQ5NjItNDNkMS04NWVlLTlkYzEwZmJiOGY2YyIsInN1YiI6Imh0dHBzOi8vZXhhbXBsZWJhbmsuY29tL2FwaS9vcGVuLWJhbmtpbmcvdjMuMS9jYnBpaS9mdW5kcy1jb25maXJtYXRpb24tY29uc2VudHMvODgzNzkiLCJhdWQiOiI3dW14NW5UUjMzODExUXlRZmkiLCJldmVudHMiOnsidXJuOnVrOm9yZzpvcGVuYmFua2luZzpldmVudHM6cmVzb3VyY2UtdXBkYXRlIjp7InN1YmplY3QiOnsic3ViamVjdF90eXBlIjoiaHR0cDovL29wZW5iYW5raW5nLm9yZy51ay9yaWRfaHR0cDovL29wZW5iYW5raW5nLm9yZy51ay9ydHkiLCJodHRwOi8vb3BlbmJhbmtpbmcub3JnLnVrL3JpZCI6Ijg4Mzc5IiwiaHR0cDovL29wZW5iYW5raW5nLm9yZy51ay9ydHkiOiJmdW5kcy1jb25maXJtYXRpb24tY29uc2VudHMiLCJodHRwOi8vb3BlbmJhbmtpbmcub3JnLnVrL3JsayI6W3sidmVyc2lvbiI6InYzLjEiLCJsaW5rIjoiaHR0cHM6Ly9leGFtcGxlYmFuay5jb20vYXBpL29wZW4tYmFua2luZy92My4xL2NicGlpL2Z1bmRzLWNvbmZpcm1hdGlvbi1jb25zZW50cy84ODM3OSJ9XX19LCJ1cm46dWs6b3JnOm9wZW5iYW5raW5nOmV2ZW50czpjb25zZW50LWF1dGhvcml6YXRpb24tcmV2b2tlZCI6e319LCJ0eG4iOiJkZmM1MTYyOC0zNDc5LTRiODEtYWQ2MC0yMTBiNDNkMDIzMDYiLCJ0b2UiOjE1MTYyMzkwMjJ9.jKq6U1jKvoEF5mFAgtlJxtzaTZ2VJFsm8NoXoLOFDPc

Decoded JWT Body - Event Notification Payload

    "iss": "https://examplebank.com/",   "iat": 1516239022,   "jti": "b460a07c-4962-43d1-85ee-9dc10fbb8f6c",   "sub": "https://examplebank.com/api/open-banking/v3.1/cbpii/funds-confirmation-consents/88379",   "aud": "7umx5nTR33811QyQfi",   "events": {     "urn:bh:org:openbanking:events:resource-update": {       "subject": {         "subject_type": "http://openbanking.org.bh/rid_http://openbanking.org.bh/rty",         "http://openbanking.org.bh/rid": "88379",         "http://openbanking.org.bh/rty": "funds-confirmation-consents",         "http://openbanking.org.bh/rlk": [           {             "version": "v3.1",             "link": "https://examplebank.com/api/open-banking/v3.1/cbpii/funds-confirmation-consents/88379"           }         ]       }     },     "urn:bh:org:openbanking:events:consent-authorization-revoked": {}   },   "txn": "dfc51628-3479-4b81-ad60-210b43d02306",   "toe": 1516239022 }

4.2.2 POST Event Notification Response

HTTP/1.1 202 Accepted

x-fapi-interaction-id: db54268f-2cc7-47e3-bf3c-4b5a7d08a614

4.3  Send Event Notification - AIS Consent Authorisation Revoked

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

  • consent-authorization-revoked

4.3.1 POST Event Notification Request

POST /event-notifications HTTP/1.1 x-fapi-interaction-id: db54268f-2cc7-47e3-bf3c-4b5a7d08a614 Content-Type: application/jwt   eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJodHRwczovL2V4YW1wbGViYW5rLmNvbS8iLCJpYXQiOjE1MTYyMzkwMjIsImp0aSI6ImI0NjBhMDdjLTQ5NjItNDNkMS04NWVlLTlkYzEwZmJiOGY2YyIsInN1YiI6Imh0dHBzOi8vZXhhbXBsZWJhbmsuY29tL2FwaS9vcGVuLWJhbmtpbmcvdjMuMS9haXNwL2FjY291bnQtYWNjZXNzLWNvbnNlbnRzL2FhYy0xMjM0LTAwNyIsImF1ZCI6Ijd1bXg1blRSMzM4MTFReVFmaSIsImV2ZW50cyI6eyJ1cm46dWs6b3JnOm9wZW5iYW5raW5nOmV2ZW50czpjb25zZW50LWF1dGhvcml6YXRpb24tcmV2b2tlZCI6eyJzdWJqZWN0Ijp7InN1YmplY3RfdHlwZSI6Imh0dHA6Ly9vcGVuYmFua2luZy5vcmcudWsvcmlkX2h0dHA6Ly9vcGVuYmFua2luZy5vcmcudWsvcnR5IiwiaHR0cDovL29wZW5iYW5raW5nLm9yZy51ay9yaWQiOiJhYWMtMTIzNC0wMDciLCJodHRwOi8vb3BlbmJhbmtpbmcub3JnLnVrL3J0eSI6ImFjY291bnQtYWNjZXNzLWNvbnNlbnRzIiwiaHR0cDovL29wZW5iYW5raW5nLm9yZy51ay9ybGsiOlt7InZlcnNpb24iOiJ2My4xIiwibGluayI6Imh0dHBzOi8vZXhhbXBsZWJhbmsuY29tL2FwaS9vcGVuLWJhbmtpbmcvdjMuMS9haXNwL2FjY291bnQtYWNjZXNzLWNvbnNlbnRzL2FhYy0xMjM0LTAwNyJ9XX19fSwidHhuIjoiZGZjNTE2MjgtMzQ3OS00YjgxLWFkNjAtMjEwYjQzZDAyMzA2IiwidG9lIjoxNTE2MjM5MDIyfQ.aBWXTb4_zNxY5u4TuyuAYCtHMFXntJeSnNBw6jFySF8

Decoded JWT Body - Event Notification Payload 

{            "iss": "https://examplebank.com/",            "iat": 1516239022,            "jti": "b460a07c-4962-43d1-85ee-9dc10fbb8f6c",            "sub": "https://examplebank.com/api/open-banking/v3.1/aisp/account-access-consents/aac-1234-007",            "aud": "7umx5nTR33811QyQfi",            "events": {                       "urn:bh:org:openbanking:events:consent-authorization-revoked": {                                  "subject": {                                             "subject_type": "http://openbanking.org.bh/rid_http://openbanking.org.bh/rty",                                             "http://openbanking.org.bh/rid": "aac-1234-007",                                             "http://openbanking.org.bh/rty": "account-access-consents",                                             "http://openbanking.org.bh/rlk": [{                                                                  "version": "v3.1",                                                                  "link": "https://examplebank.com/api/open-banking/v3.1/aisp/account-access-consents/aac-1234-007"                                                        }                                             ]                                  }       }    },            "txn": "dfc51628-3479-4b81-ad60-210b43d02306",            "toe": 1516239022 }

 4.3.2 POST Event Notification Response

HTTP/1.1 202 Accepted x-fapi-interaction-id: db54268f-2cc7-47e3-bf3c-4b5a7d08a614

 

  • No labels