Notification API

The bLink Notification API provides event-driven data synchronization that enables Service Providers to inform Service Users about changes to resources. It ensures timely synchronization between the Service Provider's resource state and the Service User's replicated data without requiring constant polling. Notifications are triggered when a resource changes state —such as being created, updated, or deleted— allowing Service Users to fetch only the impacted data.

Key Features

• Generic and reusable framework applicable to multiple business APIs.
• Supports Real-Time Notifications (push) and Aggregated Polling (pull).
• Subscription-based model: Service Users subscribe per API, consent, and Service Provider.
• Participant's configuration (Webhook URL, activation of Notification API) on the bLink platform.
• Standardized notification format including eventType, resourceLink, and created timestamp.
• Secure communication via mTLS.
• Event Store offered as software-as-a-service by bLink for Aggregated Polling.

Notification API Components

Component	Description
Subscription	The Service User creates and manages subscriptions at the Service Provider.
Real-Time Notification	The Service Provider pushes event notifications to the Service User.
Aggregated Polling	The Service User polls for missed or accumulated event notifications from the Service Provider.

Subscription

Each Service User can create one subscription per combination of Consent, Service Provider, API, and Version. Subscriptions can be created, updated, retrieved, or deleted using standard RESTful endpoints. Each subscription contains a set of event types for which notifications shall be triggered. The list of supported event types is defined in the specification of each Business API. The heartbeat event type is common to all Business APIs. The other event types are specific for each Business API.

Subscription Endpoints

Operation	Method	URL
Create	POST	<api-use-case>/<api-version>/event-subscriptions
Retrieve list	GET	<api-use-case>/<api-version>/event-subscriptions
Retrieve one	GET	<api-use-case>/<api-version>/event-subscriptions/{id}
Update	PUT	<api-use-case>/<api-version>/event-subscriptions/{id}
Delete	DELETE	<api-use-case>/<api-version>/event-subscriptions/{id}

Subscription Data Type

Example of a subscription:

{
  "eventSubscriptionId": "7c5f40fc-1b29-4263-a2dd-e127a22a947f",
  "eventTypes": ["order:doneForDay", "order:replaced"]
}

Create Subscription Flow

The diagram below illustrates the steps for successfully creating a subscription with the Service Provider.

Real-Time Notification

When a resource is updated and a subscription with an applicable event type exists for this resource, the Service Provider sends a notification to the Service User’s endpoint. The notification contains a set of fields common to all Business APIs and optionally a set of Business API specific fields. Common fields are:

• resourceLink: a link to the resource that has changed.
• eventSubscriptionId: the ID of the subscription for which the event occurred.
• eventType: the event type that occurred.
• created: timestamp when the event occurred.

Real-Time Notification Endpoints

Operation	Method	URL
Create	POST	<api-use-case>/<api-version>/event-notifications

Real-Time Notification Data Type

Example of a notification:

{
  "version": "1.0",
  "eventSubscriptionId": "7c5f40fc-1b29-4263-a2dd-e127a22a947f",
  "eventType": "order:replaced",
  "resourceLink": "/api/.../orders/abcd1234",
  "created": "2022-10-26T07:58:30.996+0100",
  "id": "120066c9-58a1-432b-aa60-712fae7f143e"
}

Real-Time Notification Flow

The diagram illustrates the steps for successfully sending a notification from the Service Provider to the Service User.

Aggregated Polling

Service Users can retrieve missed or accumulated notifications by polling from the Service Provider. Optionally, prior to polling for notifications, Service Users can query for all subscriptions with pending notifications at the Service Provider. For both operations Service Users might set the fromEventDateTime parameter to filter for notifications that were created after the specified timestamp. Aggregated Polling uses the same notification object type as Real-Time Notification.

An Event Store is offered by bLink as software-as-a-service for Aggregated Polling. All notifications pushed by the Service Provider may be stored in the bLink Event Store and can then be queried by the Service User using the Aggregated Polling endpoints.

Aggregated Polling Endpoints

Operation	Method	URL
Search subscriptions with pending events	GET	<api-use-case>/<api-version>/event-subscriptions/search?fromEventDateTime=<dateTime>
Poll aggregated events	GET	<api-use-case>/<api-version>/event-subscriptions/{id}/event-notifications?fromEventDateTime=<dateTime>

Aggregated Polling Flow

The diagram below illustrates the flow for successfully querying subscriptions with pending notifications followed by polling all notifications for one of these subscriptions. The case where bLink is returning the data from its Event Store is illustrated here.

1. The Service User queries for all subscriptions with pending events. If the fromEventDateTime parameter is set only those subscriptions will be returned, with pending notifications that are newer than the specified timestamp.
2. A list of subscription IDs with pending notifications is returned by bLink from its Event Store.
3. The Service User polls for notifications for one of these subscription IDs. If the fromEventDateTime parameter is set only those notifications will be returned that are newer than the specified timestamp.
4. A list of notifications is returned by bLink from its Event Store.

Currently Available APIs

The Notification API is currently available for the following bLink API modules:

API use case	API version	API sepcification
Open Wealth Order Placement	v2	API specification