Webhooks: Event Subscription API

Features

• There shall be zero or one subscription per combination of consent, SP, SU, API and major version of the API.
• Subscriptions may be retrieved, updated and deleted by the SU.
• The subscriptions requests are formatted as JSON.

Data model

The subscription request shall contain a set of common fields and optionally a set of Business API specific fields:

Fields	Type
Common fields	eventTypes [1..n] callbackUrl [0..1]
Business API specific fields	???

The subscription request shall contain the following field(s):

• eventTypes [1..n]
• callbackUrl [0..1]

The list of supported EventTypes and any additional fields are to be defined by the Business API owners as required.

EventTypes shall be defined in the form <Resource>:<Action> where <Resource> should the name of the resource in singular and <Action> should be a verb in past tense, e.g. Order:Partially_Filled. Both <Resource> and <Action> may contain underscores.

An empty EventTypes field causes the SP to stop sending notifications, the subscription resource is let alive. If event-types are added to the EventTypes field again, only subsequently generated events are sent by the SP. Any missed events must be retrieved by the SU using aggregated polling.

Each subscription request may include a callbackUrl to allow use of this specification outside of implemented API context. The callbackUrl, if present, may not forwarded to the SP. No error is returned to the SU.

Catch-All EventType

Business API owner decides on support of Catch-All EventTypes. When it is implemented, care must be taken that the introduction of a new EventType may result in a breaking change. The SUs should be prepared to handle unknown EventTypes. As a best practice the handling of unknown EventTypes by the SU should be clearly specified by the Business API owner. One way the SU could handle unknown EventTypes would be to fetch the resource using the link in the notification and to update the local state accordingly. Another way would be to subscribe explicitly to all EventTypes known to the SU.

Heartbeat EventType

The implementation of a heartbeat EventType is recommended. The heartbeat event is generated by the SP at a given interval. The resource link may be empty or may point to a health-check endpoint at the SP (details to be specified). If a Catch-All EventType is implemented, the heartbeat EventType is to be included.

Flow

Diagram

sequenceDiagram
    participant SU
    participant bLink
    participant ResourceServer
    participant NotificationService
    Note over SU,NotificationService: Setup Event Subscription Configuration
    loop over all consents
        activate SU
        SU ->> bLink: POST EventSubscription
        activate bLink
        bLink ->> ResourceServer: POST EventSubscription
        activate ResourceServer
        ResourceServer ->> ResourceServer: Store ID/consent of RO in context of subscription<br>(identified by access token from POST request)
        ResourceServer -->> bLink: HTTP 201 (Created), EventSubscriptionId
        deactivate ResourceServer
        bLink -->> SU: HTTP 201 (Created), EventSubscriptionId
        deactivate bLink

        SU ->> SU: Store subscription ID in context of consent
        deactivate SU
    end

Loading

Description "Setup Subscription"

1. SU posts subscription request to SP (notifier).

Example:

POST /api/bankingservices/b-link/order-placement/v1/event-subscriptions HTTP/1.1
host: api-cert.six-group.com
content-type: application/json
x-corapi-target-id: 99999
authorization: bearer 65a8e1a2-7189-460a-a9c9-dadd6b426926

{
    "eventTypes": [ "Order:Created", "Order:Partially_Filled" ],
    "callbackUrl": "/ttpAPI/notifications/order-placement/"
}

Note: example shows implementation of event-subscription endpoint per API, e.g. there would be one endpoint each for customer management, custody services and order management (ca-wealth).

2. SP stores the ID / consent of the RO in the context of the subscription.

3. SP returns response with HTTP code 201 (Created) and the EventSubscriptionId in the response body.

Example:

HTTP/1.1 201 Created
content-type: application/json
location: /api/bankingservices/b-link/order-placement/v1/event-subscriptions/7c5f40fc-1b29-4263-a2dd-e127a22a947f

{
    "eventSubscriptionId": "7c5f40fc-1b29-4263-a2dd-e127a22a947f"
}

4. SU stores the EventSubscriptionId in the context of the consent.

Endpoints

Use the following endpoints to register, modify and delete event subscription resources.

Endpoint Name	Resource	Endpoint URL	Mandatory/Optional
Create event-subscription	event-subscription	POST /event-subscriptions	Optional or mandatory, as per Business API specification
Get list of event-subscriptions	list of event-subscriptions	GET /event-subscriptions	Mandatory (if the POST resource implemented)
Get event-subscription	event-subscription	GET /event-subscriptions/{EventSubscriptionId}	Mandatory (if the POST resource implemented)
Change event-subscription	event-subscription	PUT /event-subscriptions/{EventSubscriptionId}	Mandatory (if the POST resource implemented)
Delete event-subscription	event-subscription	DELETE /event-subscriptions/{EventSubscriptionId}	Mandatory (if the POST resource implemented)

These endpoints allow easy management of subscribed EventTypes within one subscription per SP, SU, consent, API and major API version. In case the SU has lost the subscription ID, it may easily be retrieved using the "Get list of EventSubscriptionIds" endpoint. This endpoint shall support cursor based paging (using cursor and limit parameters). The endpoints to register, modify and delete event subscription resources require an access token.

Example: Migrate Event Subscription for API V1 to the next major version V2

sequenceDiagram
    participant SU
    participant bLink
    participant ResourceServer
    participant NotificationService

    Note over SU,NotificationService: Initial Setup of old Event Subscription Configuration for API V1

    activate SU
    SU ->> bLink: POST EventSubscription V1
    activate bLink
    bLink ->> ResourceServer: POST EventSubscription V1
    activate ResourceServer
    ResourceServer -->> bLink: HTTP 201 (Created), EventSubscriptionId V1
    deactivate ResourceServer
    bLink -->> SU: HTTP 201 (Created), EventSubscriptionId V1
    deactivate bLink
    deactivate SU
    
    Note over SU,NotificationService: Migration Step 1: Setup new Event Subscription Configuration for API V2

    activate SU
    SU ->> bLink: POST EventSubscription V2
    activate bLink
    bLink ->> ResourceServer: POST EventSubscription V2
    activate ResourceServer
    ResourceServer -->> bLink: HTTP 201 (Created), EventSubscriptionId V2
    deactivate ResourceServer
    bLink -->> SU: HTTP 201 (Created), EventSubscriptionId V2
    deactivate bLink
    deactivate SU
    
    Note over SU,NotificationService: Migration Step 2: Delete old Event Subscription Configuration for API V1

    activate SU
    SU ->> bLink: DELETE EventSubscription V1, EventSubscriptionId V1
    activate bLink
    bLink ->> ResourceServer: DELETE EventSubscription V1
    activate ResourceServer
    ResourceServer -->> bLink: HTTP 204 (No Content)
    deactivate ResourceServer
    bLink -->> SU: HTTP 204 (No Content)
    deactivate bLink
    deactivate SU 

Loading

Error handling

When an SU tries to create a second subscription for an API and version, the SP responds with HTTP 409 (Conflict). When an SU tries to update or delete a non-existent subscription, the SP responds with HTTP 404 (Not found).