Webhooks: Roles and Responsibilities

SFTI

Conceptual
Defines basic principles of the Event Notification API.

• Subscription - Model
• Notification - Real-time - Polling - Model

Operational

• Examines conformity of Business API definition with basic principles of the Event Notification API
• Publishes the Business API on SFTI
• Validates and delivers subscription, notification, aggregated polling requests
• Limits access to Event Notification Endpoints to authorized parties only
• Enforces mTLS-authentication on all connections
• Publishes Event Notification support by SP (if at all and with which notification mechanisms)
• Stores Event Notification Endpoints of SUs (one per SU, API).

Business API owner

Current owners

• AIS & PSS API: SFTI Common API group
• Open Wealth API: OpenWealth Association

Conceptual

• Defines relevant EventTypes (this includes heartbeat EventType if required).
• Defines status codes and explanations (to be presented to end-users) and any translations required.
• Defines additional payload in Event Notifications (ensuring that no CID is included).
• Defines the languages relevant for translations for this API.
• Defines if Event Notification shall or can be implemented and which delivery mechanisms shall be supported mandatory or optional.
• Defines the retention period for events at the SP.
• Versions EventTypes, status codes and descriptions along with the Business API
• Publishes Event Notification API as part of the Business API definition (Swagger).

Service Provider (SP)

Technical

• Generates events whenever resources are created, updated or deleted. The events must contain all mandatory fields according to the Business API specification, i.e. the version, status codes, EventType and a unique timestamp and a UUID v4.
• Makes the events retrievable for the SU for the retention period defined by the Business API.
• Delivers events to the SU strictly in the order they were created.
• Implements management of Subscriptions as defined by SFTI.
• Implements notification mechanisms as specified by the Business API Owner.
• Handles Real-Time notifications responses with HTTP code 429 (Too Many Requests) from SU properly, which includes handling of the 'Retry-After' response HTTP header if present.

Service User (SU)

Technical

• Creates at maximum one Subscription per SP according to the Business API specification. The subscription must contain all mandatory fields, i.e. the version, EventTypes.
• Implements an endpoint for Real-time Event Notifications, if required.
• Must be able to bring events in the correct order by using time-stamp data and linked predecessor UUID v4.
• Must be able to detect duplicate event delivery (based on time-stamp and UUID v4 per SP).
• Implements Aggregated Polling, if used instead of real-time notifications or for recovery of lost/missed events in error situations.
• Implements throttling to protect from being flooded by SP if required. Must send responses with HTTP code 429, preferably including HTTP header 'Retry-After'.