Skip to main content

Notification Flow

The following diagram shows the high-level phases of the Notification Flow. Detailed step descriptions are provided in the sections below.

High-level Flow​

Consent 3.0 replaces continuous polling with an event-subscription model: the Service User registers once for the event types it cares about (consent:changed, consent:revoked), and is then notified either by webhook push or by aggregated polling.

  1. Subscribe
    The Service User creates an event subscription for the event types it wants to receive. See Details
  2. Consent change occurs
    A consent-relevant change happens at the Service Provider (e.g. revocation) and bLink matches it against active subscriptions for the associated grant_id.
  3. Notification delivery
    bLink delivers the notification either by pushing it to the Service User's webhook endpoint, or by making it available for aggregated polling if the Service User has no webhook registered (or the push failed and is pending retry). See Details

Subscribe​

  1. The Service User creates a subscription, listing the event types it wants to be notified about.
POST "api/consent-flow/v3/event-subscriptions"
-H "Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.auth123"
-H "Content-Type: application/json"
-H "X-Correlation-ID: 9b2d1a3c-6e4f-4b8a-9d2e-1f3a5c7b9e0d"
-H "X-CorAPI-Target-ID: IIDP99999"
-H "X-PSU-User-Agent: AUTO"
-H "User-Agent: MySU/1.0"
--data '{
  "eventTypes": ["consent:changed", "consent:revoked"]
}'

Successful response (201)​

{
  "id": "7c5f40fc-1b29-4263-a2dd-e127a22a947f",
  "eventTypes": ["consent:changed", "consent:revoked"]
}
  1. bLink validates the requested eventTypes against the EventType enum (heartbeat, consent:changed, consent:revoked).
  2. bLink returns the created subscription including its generated id, which is referenced by later notifications (eventSubscriptionId) and by the polling endpoint.
  3. The Service User can later retrieve, update (PUT /event-subscriptions/{eventSubscriptionId}), or delete (DELETE /event-subscriptions/{eventSubscriptionId}) the subscription, or list/search existing ones via GET /event-subscriptions and GET /event-subscriptions/search.

Notification delivery​

Webhook push​

  1. A consent-relevant change occurs at the Service Provider and is reported to bLink.
  2. bLink resolves which event subscription(s) match the change and builds an EventNotification.
  3. bLink pushes the notification to the Service User's registered webhook endpoint.
POST "https://su.example.com/event-notifications"
-H "Content-Type: application/json"
-H "X-Correlation-ID: 2f6a8c1d-4b3e-4a9f-8c7d-5e1b9a3f6d2c"
-H "X-CorAPI-Target-ID: IIDP99999"
-H "X-PSU-User-Agent: AUTO"
-H "User-Agent: bLink/1.0"
--data '{
  "id": "120066c9-58a1-432b-aa60-712fae7f143e",
  "version": "1.0",
  "eventType": "consent:revoked",
  "eventSubscriptionId": "7c5f40fc-1b29-4263-a2dd-e127a22a947f",
  "resourceLink": "/permissions/3f5dd8a4-7e3a-47af-92e8-2e2bc5bcd011",
  "creationDateTime": "2026-09-07T07:58:30.996+0100"
}'

Accepted response (202).​

No response body.

Rate-limited response (429)​

{
  "type": "/problems/TECHNICAL_ERROR",
  "title": "Too Many Requests - Reduce notification delivery rate.",
  "detail": "Notification delivery rate exceeded, retry after the indicated delay",
  "instance": "/event-notifications"
}
  1. The Service User acknowledges receipt with 202. Any 2xx marks the notification delivered.
  2. A 4xx response (other than 429) is treated as a permanent failure bLink does not retry.
  3. A 5xx, 429, or timeout triggers a retry with exponential backoff, up to a 24-hour retry window, after which the notification is dead-lettered and raised for operational alerting.
  4. The Service User deduplicates on EventNotification.id, since retries may redeliver the same event.

Aggregated polling (fallback / recovery)​

  1. A Service User without a webhook endpoint, or recovering from a gap after exhausted webhook retries, polls for notifications it may have missed.
GET "api/consent-flow/v3/event-subscriptions/7c5f40fc-1b29-4263-a2dd-e127a22a947f/event-notifications?fromEventDateTime=2026-09-07T00:00:00.000%2B0100"
-H "X-Correlation-ID: 5a7e2b1c-9d4f-4c8a-8b6e-3f1a7c9e5b2d"
-H "X-CorAPI-Target-ID: IIDP99999"
-H "X-PSU-User-Agent: AUTO"
-H "User-Agent: MySU/1.0"

Successful response (200)​

[
  {
    "id": "120066c9-58a1-432b-aa60-712fae7f143e",
    "version": "1.0",
    "eventType": "consent:revoked",
    "eventSubscriptionId": "7c5f40fc-1b29-4263-a2dd-e127a22a947f",
    "resourceLink": "/permissions/3f5dd8a4-7e3a-47af-92e8-2e2bc5bcd011",
    "creationDateTime": "2026-09-07T07:58:30.996+0100"
  }
]
  1. bLink returns all notifications for that subscription since fromEventDateTime, paginated via cursor/limit and the X-nextCursor response header.
  2. A 429 response (standard429) signals the Service User to poll less frequently; bLink returns a Retry-After header indicating the minimum delay.

See the Notification API concept for bLink's existing notification service that this design builds on.

Last updated on