Webhooks: Aggregated Polling API

Features

Aggregated polling uses a simple flow model:

• Aggregated polling is executed for each consent. The subscription ID and the corresponding access token must be provided with the request. This ensures in the on-prem case that SUs can only fetch notifications for their own users.
• SU can retrieve all event notifications having a given timestamp or newer by supplying the fromEventDate parameter.
• SU can retrieve all event notifications by omitting the fromEventDate parameter. The minimum event retention time is defined by the Business API owner. A minimum retention time of zero is permitted.
• The maximum number of event notifications returned can be set with the limit parameter. The limit parameter has a default value of 1000 which applies if the limit parameter is omitted.
• The SU is responsible to track the correct offset for retrieving notifications. There is no mechanism for the SP to track which SU has successfully retrieved and processed which notification.
• Uses same notification object as Real-time Event Notification API.
• May be used as recovery or reconciliation mechanism for event notifications missed/lost on the Real-time Event Notification API
• The notifications are formatted as JSON.
• The polling requests with the fromEventDate parameter return notifications that have already been received. This ensures that notifications with the same timestamp cannot be accidentally lost. The SU must be able to recognize the double or multiple receipt of a notification based on the event-id.

Data model

The polling response contains a list of event notifications sorted by event date in ascending order.

The event notifications have the same structure as in the Real-time Event Notification API.

Flow

Diagram

sequenceDiagram
    participant SU
    participant bLink
    participant ResourceServer
    participant NotificationService

    loop
        opt Optionally
            Note over SU,NotificationService: Step 1: Lookup with pending events
                loop until empty response
                activate SU
                SU ->> bLink: Lookup subscriptions with pending events
                activate bLink
                bLink ->> NotificationService: Lookup subscriptions {cursor, limit, timestamp}
                activate NotificationService
                NotificationService -->> bLink: HTTP 200 (OK), zero or more EventSubscriptionIds
                deactivate NotificationService
                bLink -->> SU: HTTP 200 (OK), zero or more EventSubscriptionIds
            end
        end
        loop over all subscriptions or just the subscriptions from step 1
            loop until empty response
                note over SU,NotificationService: Step 2: Poll for new events

                SU ->> bLink: Poll for events
                activate bLink
                bLink ->> NotificationService: Poll for events of the subscription {cursor, limit, timestamp}
                activate NotificationService
                NotificationService -->> bLink: HTTP 200 (OK), zero or more Events
                deactivate NotificationService
                bLink -->> SU: HTTP 200 (OK), zero or more Events

                opt If SU requires full resources
                    loop iterate over events received
                        SU ->> bLink: GET resource
                        activate bLink
                        bLink ->> ResourceServer: GET resource
                        activate ResourceServer
                        ResourceServer -->> bLink: HTTP 200 (OK), response
                        deactivate ResourceServer
                        bLink -->> SU: HTTP 200 (OK), response
                        deactivate bLink
                    end
                end
            end
        end

        SU ->> SU: wait
    end

Loading

Description "Aggregated Polling"

1. Optionally: For every subscription the SU determines the most recent timestamp of the notifications received. From this list of timestamps the SU selects the oldest one to search for pending notifications at SP.

Example:

GET /api/bankingservices/b-link/order-placement/v1/event-subscriptions/search?fromEventDate=2022-10-26T07:58:30.996+0100&limit=100 HTTP/1.1
host: api-cert.six-group.com
content-type: application/json
user-agent: xyz
x-correlation-id: 3a100824-7c38-4b3e-afb5-d8824097e52e
x-corapi-target-id: 99999
x-psu-ip-address: AUTO
x-psu-user-agent: AUTO
x-corapi-api-version: 1.0

2. SP returns response containing a list of zero or more event_subscription_ids with pending events:

HTTP/1.1 200 OK
content-type: application/json

{
    "eventSubscriptionIds": [ "7c5f40fc-1b29-4263-a2dd-e127a22a947f" ]
}

3. SU iterates over all event_subscription_ids or just the ones with pending events from the lookup request (steps 1 and 2).

• SU sends polling request to SP.

Example:

GET /api/bankingservices/b-link/order-placement/v1/event-subscriptions/7c5f40fc-1b29-4263-a2dd-e127a22a947f/event-notifications?fromEventDate=2022-10-26T07:58:30.996+0100&limit=500 HTTP/1.1
host: api-cert.six-group.com
content-type: application/json

x-corapi-target-id: 99999
x-corapi-api-version: 1.0
x-correlation-id: c604c0bb-1c8a-474f-a548-ba2edded8377
authorization: bearer 65a8e1a2-7189-460a-a9c9-dadd6b426926

• SU returns response containing zero or more event notifications with HTTP code 200 (Accepted).

Example 1: non-empty response

HTTP/1.1 200 OK
content-type: application/json
x-nextCursor: abcd1234

{
    "eventNotifications": [
        {
            "version": "1.0",
            "eventSubscriptionId": "7c5f40fc-1b29-4263-a2dd-e127a22a947f",
            "status": "Order:Partially_Filled",
            "resourceLink": "/api/bankingservices/b-link/order-placement/v1/orders/abcd1234",
            "created": "2022-10-26T07:58:30.996+0100",
            "id": "120066c9-58a1-432b-aa60-712fae7f143e"
        },
        {       
            "version": "1.0",
            "eventSubscriptionId": "7c5f40fc-1b29-4263-a2dd-e127a22a947f",
            "status": "Order:Created",
            "resourceLink": "/api/bankingservices/b-link/order-placement/v1/orders/efgh5678",
            "created": "2022-10-26T09:12:21.345+0100",
            "id": "a7a24853-8500-402f-bdfb-5f6ff59fe509"
        }
    ]
}

Example 2: empty response (event-id "a7a24853-8500-402f-bdfb-5f6ff59fe509" is the most recent one in this example)

HTTP/1.1 200 OK
content-type: application/json
x-nextCursor: abcd1234

{
"eventNotifications": []
}

Rate-limiting

When an SU sends too many lookup or polling requests in a given amount of time the SP shall respond with HTTP 429 (Too many requests). This response may contain a Retry-After header indicating how long the SU must wait before making a new request. (see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429).

Error handling and retries

Phase	Error	Handling	Flow steps
Query of subscriptions with pending events	Invalid or unknown event_subscription_ids in request	SP: ignore invalid event_subscription_ids, just return events for the known ids.	1
Poll for events	Invalid or unknown event_subscription_id in request	SP: return 404 (Not found). SU: should retrieve and reconcile the list of its subscriptions at the SP.	3

On the following occasions the query of subscriptions with pending events or the poll for the events is considered to be unsuccessful, and therefore it will be retried:

• The SU does not respond within maximum response time defined for this API.
• The SU's notification endpoint is unavailable or unreachable.
• The SU responds with any HTTP code other than 200 (or 404).

The maximum number of retries as well as the time-interval between retries is defined by the Business API owner.