Skip to main content

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

ComponentDescription
SubscriptionThe Service User creates and manages subscriptions at the Service Provider.
Real-Time NotificationThe Service User pushes event notifications to the Service Provider.
Aggregated PollingThe 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

OperationMethodURL
CreatePOST<api-use-case>/<api-version>/event-subscriptions
Retrieve listGET<api-use-case>/<api-version>/event-subscriptions
Retrieve oneGET<api-use-case>/<api-version>/event-subscriptions/{id}
UpdatePUT<api-use-case>/<api-version>/event-subscriptions/{id}
DeleteDELETE<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.

Create Subscription

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

OperationMethodURL
CreatePOST<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.

Push Notification

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

OperationMethodURL
Search subscriptions with pending eventsGET<api-use-case>/<api-version>/event-subscriptions/search?fromEventDateTime=<dateTime>
Poll aggregated eventsGET<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.

Push Notification

  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 caseAPI versionAPI sepcification
Open Wealth Order Placementv2API specification