1. Version Control

Version	Date	Description of Changes
Bahrain OBF v1.0.0	28th Oct 2020	Initial Release

2. Overview

The Event Notification subscription API Profile describes the flows and common functionality to allow an AISP/ PISP to:

Register an event subscription with an ASPSP to subscribe to event notifications
A subscription can enable real time event notifications via an HTTP callback from the ASPSP, and aggregated polling by the AISP/PISP
Specify a list of event types to be notified on
Optionally read, update or delete a registered event subscription

AISPs / PISPs can receive all or specific event types via the Real Time Event Notification API and/or the Aggregated Polling 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.

The following APIs have been elaborated below:

Real-Time Notification: ASPSP shares the notifications with the AISP/ PISP real time, as soon as the event occurs

Aggregated Polling (Pull Notifications): ASPSP shares the notifications to AISPs/ PISPs in an aggregated set, upon request

The Event Subscription resource is used by an AISP/PISP to subscribe to events with an ASPSP.

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

3. Endpoints

An AISP/ PISP will set up and maintain its event subscription details (URL, event types and version number) using the event-subscription resource.

S. No.	Resource	HTTP Operation	Endpoint	Mandatory	Scope	Grant Type	Message Signing	Idempotency Key	Request Object	Response Object
3.1	event-subscription	POST	POST /event-subscriptions	Optional	accounts payments	Client Credentials	Signed Request Signed Response	No	OBEventSubscription	OBEventSubscriptionResponse
3.2	event-subscription	GET	GET /event-subscriptions	Mandatory (if resource POST implemented)	accounts payments	Client Credentials	Signed Response	No	n/a	OBEventSubscriptionsResponse
3.3	event-subscription	PUT	PUT /event-subscriptions/{EventSubscriptionId}	Conditional	accounts payments	Client Credentials	Signed Request Signed Response	No	OBEventSubscriptionResponse	OBEventSubscriptionResponse
3.4	event-subscription	DELETE	DELETE /event-subscriptions/{EventSubscriptionId}	Conditional	accounts payments	Client Credentials	n/a	No	n/a	n/a

3.1 POST /event-subscriptions

The API endpoint allows the AISP/PISP to ask an ASPSP to create a new event-subscription resource.

The POST action allows the AISP/ PISP to register an event subscription for an AISP/ PISP to access event notifications
The ASPSP creates the event-subscription resource and responds with a unique EventSubscriptionId to refer to the resource
An ASPSP must respond with a 409 error if an event-subscription exists for that AISP/ PISP

3.2 GET /event-subscriptions

The API endpoint allows the AISP/ PISP to ask an ASPSP to retrieve its event-subscription resource.

The ASPSP retrieves the event-subscription resource and responds with the resource

3.3 PUT /event-subscriptions/{EventSubscriptionId}

The API endpoint allows the AISP/ PISP to ask an ASPSP to update an event-subscription resource.

The PUT action allows the AISP/ PISP to update an event subscription for an AISP/ PISP to access event notifications
The ASPSP updates the event-subscription resource and responds with the updated resource

3.4 DELETE /event-subscriptions/{EventSubscriptionId}

The API endpoint allows the AISP/ PISP to ask an ASPSP to delete an event-subscription resource.

The ASPSP deletes the event-subscription resource

4. Data Model

4.1 Event Subscription - Request

The OBEventSubscription object will be used for the call to:

POST /event-subscriptions

4.1.1 UML Diagram

4.1.2 Notes

For the OBEventSubscription object:

AISP/ PISP must not provide CallbackUrl, when subscribing for Aggregated Polling only
AISP/ PISP must provide the Version of Resources, for which they want to subscribe the events for. E.g. if supplied with value "3.1", AISP/ PISP indicates the subscription for the change in state of resources created in v3.1 version
EventTypes usage:
- AISPs/ PISPs may provide a list of event types to subscribe to specific events
- AISPs/ PISPs may omit this field to subscribe to all supported events

4.1.3 Data Dictionary

Name	Occurrence	XPath	Enhanced Definition	Class/ Datatype	Codes	Pattern
OBEventSubscription		OBEventSubscription		OBEventSubscription
Data	1..1	OBEventSubscription/Data		OBEventSubscription/Data
CallbackUrl	0..1	OBEventSubscription/Data/CallbackUrl	Callback URL for an AISP/ PISP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to	String:URI
Version	1..1	OBEventSubscription/Data/Version	Version for the event notification	String
EventTypes	0..n	OBEventSubscription/Data/EventTypes	Array of event types the subscription applies to	Array:String	Enum: urn:bh:org:openbanking:events:resource-update urn:bh:org:openbanking:events:account-access-consent-linked-account-update urn:bh:org:openbanking:events:consent-authorization-revoked

4.2 Event Subscription - Response

The OBEventSubscriptionResponse object will be used for a response to a call to:

POST /event-subscriptions
PUT /event-subscriptions/{EventSubscriptionId}

The OBEventSubscriptionResponse object will also be used for the call to:

PUT /event-subscriptions

4.2.1 UML Diagram

4.2.2 Data Dictionary

Name	Occurrence	XPath	Enhanced Definition	Class/ Datatype	Codes	Pattern
OBEventSubscriptionResponse		OBEventSubscriptionResponse		OBEventSubscriptionResponse
Data	1..1	OBEventSubscriptionResponse/Data		OBEventSubscriptionResponse/Data
EventSubscriptionId	1..1	OBEventSubscriptionResponse/Data/EventSubscriptionId	Unique identification as assigned by the ASPSP to uniquely identify the callback URL resource	String
CallbackUrl	0..1	OBEventSubscriptionResponse/Data/CallbackUrl	Callback URL for an AISP/ PISP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to	String:URI
Version	1..1	OBEventSubscriptionResponse/Data/Version	Version for the event notification	String
EventTypes	0..n	OBEventSubscriptionResponse/Data/EventTypes	Array of event types the subscription applies to	Array:String	Enum: urn:bh:org:openbanking:events:resource-update urn:bh:org:openbanking:events:account-access-consent-linked-account-update urn:bh:org:openbanking:events:consent-authorization-revoked

4.3 Event Subscriptions - Response

The OBEventSubscriptionsResponse object will be used for a response to a call to:

GET /event-subscriptions

4.3.1 UML Diagram

4.3.2 Data Dictionary

Name	Occurrence	XPath	Enhanced Definition	Class/ Datatype	Codes	Pattern
OBEventSubscriptionsResponse		OBEventSubscriptionsResponse		OBEventSubscriptionsResponse
Data	1..1	OBEventSubscriptionsResponse/Data		OBEventSubscriptionsResponse/Data
EventSubscription	0..n	OBEventSubscriptionsResponse/Data/EventSubscription		OBEventSubscriptionsResponse/Data/EventSubscription
EventSubscriptionId	1..1	OBEventSubscriptionsResponse/Data/EventSubscription/EventSubscriptionId	Unique identification as assigned by the ASPSP to uniquely identify the callback url resource	String
Url	0..1	OBEventSubscriptionsResponse/Data/EventSubscription/Url	Callback URL for an AISP/ PISP hosted service. Will be used by ASPSPs, in conjunction with the resource name, to construct a URL to send event notifications to	String:URI
Version	1..1	OBEventSubscriptionsResponse/Data/EventSubscription/Version	Version for the event notification	String
EventTypes	0..n	OBEventSubscriptionsResponse/Data/EventSubscription/EventTypes	Array of event types the subscription applies to	Array:String	Enum: urn:bh:org:openbanking:events:resource-update urn:bh:org:openbanking:events:account-access-consent-linked-account-update urn:bh:org:openbanking:events:consent-authorization-revoked

5. Usage Example

5.1 Create Event Subscription

5.1.1 POST Event Subscription Request

POST /event-subscriptions

Authorization: Bearer 4ZopnFZFKjr5zDsicSQpLL

x-jws-signature: LMlmPSqzISEpar72ce5deMGue4RsZMDnZYG1bW6hdPlvriZ=..G1rrM18vVYBmdmRurS6nIR1yFHR8bGZyIJdvaB5nKGRvm35hTr==

x-fapi-interaction-id: 75bdc714-b2dg-7676-c759-780d6815689f

Content-Type: application/json

Accept: application/json

{ "Data": { "CallbackUrl": "https://AISP/ PISP.com/open-banking/event-notifications", "Version": "2.2" } }

5.1.2 POST Event Subscription Response

201 Created

x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K

x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865

Content-Type: application/json

{ "Data": { "EventSubscriptionId": "CB-101", "CallbackUrl": "https://AISP/ PISP.com/open-banking/event-notifications", "Version": "2.2" }, "Links": { "Self": "www.tbc.com" }, "Meta": {} }

5.2 GET Event Subscriptions

5.2.1 GET Event Subscription Request

GET /event-subscriptions

Authorization: Bearer 2YotnFZFEjr1zCsicMWpAA

x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865

Accept: application/json

5.2.2 GET Event Subscription Response

200 OK

x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K

x-fapi-interaction-id: 86ebcd82-8e38-4f2d-a79c-965b41d15865

Content-Type: application/json

{ "Data": { "EventSubscription": [{ "EventSubscriptionId": "CB-101", "CallbackUrl": "https://AISP/ PISP.com/open-banking/event-notifications", "Version": "2.2" }] }, "Links": { "Self": "www.tbc.com" }, "Meta": {} }