Events - v3.1.2

1. Overview
2. Endpoints
   1. POST /events
3. Data Model
   1. Aggregated Polling - Request
      1. UML Diagram
      2. Data Dictionary
   2. Aggregated Polling - Response
      1. UML Diagram
      2. Data Dictionary
   3. OBEventNotification2
      1. UML Diagram
      2. Notes
      3. Data Dictionary
   4. OBEventSubject1
      1. UML Diagram
      2. Notes
      3. Data Dictionary
   5. OBEventResourceUpdate2
      1. UML Diagram
      2. Data Dictionary
   6. OBEventConsentAuthorizationRevoked1
      1. UML Diagram
      2. Notes
      3. Data Dictionary
   7. OBEventAccountAccessConsentLinkedAccountUpdate1
      1. UML Diagram
      2. Notes
      3. Data Dictionary
4. Usage Examples
   1. Poll Only
      1. POST Events Request
      2. POST Events Response
   2. Acknowledge Only
      1. POST Events Request
      2. POST Events Response
   3. Poll and Acknowledge With Errors
      1. POST Events Request
      2. POST Events Response

Overview

The Events resource is used by a TPP to retrieve multiple signed event notifications from an ASPSP.

This resource description should be read in conjunction with a compatible Aggregated Polling Profile.

Endpoints

| Resource |HTTP Operation |Endpoint |Mandatory? |Scope |Grant Type |Message Signing |Idempotency Key |Request Object |Response Object | | — |— |— |— |— |— |— |— |— |— | | events |POST |POST /events |Optional |eventpolling |Client Credentials |N/A |No |OBEventPolling1 |OBEventPollingResponse1 |

POST /events

The endpoint allows a TPP to poll for and acknowledge and receive event notifications.

• The POST method allows the TPP to transmit their polling parameters and event notification acknowledgements.
• The ASPSP responds accordingly, sending event notifications as indicated by the TPPs polling parameters.

Data Model

Aggregated Polling - Request

The OBEventPolling1 will be used as the request payload for:

• POST /events

UML Diagram

Data Dictionary

Aggregated Polling - Response

The OBEventPollingResponse1 will be used as the response payload for:

• POST /events

UML Diagram

Data Dictionary

OBEventNotification2

This section describes the OBEventNotification2 class which is used in the Real Time and Aggregated Event Notification API sub-specifications.

Note, the OBEventNotification2 object is aligned with the Security Event Token (https://tools.ietf.org/html/rfc8417). It acts as a wrapper for events contained within the events claim.

UML Diagram

Notes

• The rid, rty and rlk claims are prefixed with the OB namespace http://openbanking.org.uk in the data model. The namespace has been removed from the diagram for clarity.

Data Dictionary

OBEventSubject1

This section describes the OBEventSubject1 class which is used in the OBEventResourceUpdate2, OBEventConsentAuthorizationRevoked1 and OBEventAccountAccessConsentLinkedAccountUpdate1 classes.

UML Diagram

Notes

• The rid, rty and rlk claims are prefixed with the OB namespace http://openbanking.org.uk in the data model. The namespace has been removed from the diagram for clarity.

• The array of resource links (http://openbanking.org.uk/rlk) must contain links to all supported versions of the resource.

Data Dictionary

OBEventResourceUpdate2

This section describes the OBEventResourceUpdate2 class which is used in the OBEventNotification2 resource.

UML Diagram

Data Dictionary

OBEventConsentAuthorizationRevoked1

This section describes the OBEventConsentAuthorizationRevoked1 class which is used in the OBEventNotification2 resource.

UML Diagram

Notes

For the OBEventConsentAuthorizationRevoked1 object:

• The subject claim must be populated if the Event Notification does not include a urn:uk:org:openbanking:events:resource-update event.

Data Dictionary

OBEventAccountAccessConsentLinkedAccountUpdate1

This section describes the OBEventAccountAccessConsentLinkedAccountUpdate1 class which is used in the OBEventNotification2 resource.

UML Diagram

Notes

For the OBEventAccountAccessConsentLinkedAccountUpdate object:

• The http://openbanking.org.uk/rty claim must be populated with “account-access-consent”.

Data Dictionary

Usage Examples

Note for the sake of readability the SETs shown in examples are shorted.

Poll Only

POST Events Request

POST /event HTTP/1.1

Authorization: Bearer 7b99f6c331e841dab811176e25d57ca7
Content-Type: application/json
x-fapi-interaction-id: 1af4c0e6b5da49f6b1aebf439e87c199

{
  "returnImmediately": true
}

POST Events Response

POST /event HTTP/1.1

Content-Type: application/json
x-fapi-interaction-id: 1af4c0e6b5da49f6b1aebf439e87c199

{
  "sets": {
    "b6a68c1db7fc4c178fd7d8a41b9ef85c": "eyJhbG...NEysZ4",
    "2644f8cbc8294325ad103ddfc4a5b15d": "eyJhbG...Qssw5c",
    "1fd954d5fb964afb97deee232bb88d1f": "eyJhbG...9kogfI"
  },
  "moreAvailable": false
}

Acknowledge Only

POST Events Request

POST /event HTTP/1.1

Authorization: Bearer 7b99f6c331e841dab811176e25d57ca7
Content-Type: application/json
x-fapi-interaction-id: 295f6c6c7b2045b2a3e91e4f1c31d681
 
{
  "maxEvents": 0,
  "ack": [ "b6a68c1db7fc4c178fd7d8a41b9ef85c" ]
}

POST Events Response

POST /event HTTP/1.1

Content-Type: application/json
x-fapi-interaction-id: 295f6c6c7b2045b2a3e91e4f1c31d681

{
  "sets": { }
}

Poll and Acknowledge With Errors

POST Events Request

POST /event HTTP/1.1

Authorization: Bearer 7b99f6c331e841dab811176e25d57ca7
Content-Type: application/json
x-fapi-interaction-id: 3fc0df586e45404abd5bbf1b23ce343d

{
  "returnImmediately": true,
  "maxEvents": 1,
  "ack": [ "2644f8cbc8294325ad103ddfc4a5b15d" ],
  "setErrs": {
    "1fd954d5fb964afb97deee232bb88d1f": {
      "err": "jwtIss",
      "description": "Issuer is invalid or could not be verified"
    }
  }
}

POST Events Response

POST /event HTTP/1.1

Content-Type: application/json
x-fapi-interaction-id: 3fc0df586e45404abd5bbf1b23ce343d

{
  "sets": {
    "25fd4432da4e4e609033a733aea68a54": "eyJhbG...8o8PLY"
  },
  "moreAvailable": true
}