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
, andcreated
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 User pushes event notifications to the Service Provider. |
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 get only results 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 will 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.
- 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. - A list of subscription IDs with pending notifications is returned by bLink from its event store.
- 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. - 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 |