Events - v3.1.6

• Overview
• Endpoints
  • POST /events
• Data Model
  • Aggregated Polling - Request
    • UML Diagram
    • Data Dictionary
  • Aggregated Polling - Response
    • UML Diagram
    • Data Dictionary
  • OBEventNotification2
    • UML Diagram
    • Notes
    • Data Dictionary
  • OBEventSubject1
    • UML Diagram
    • Notes
    • Data Dictionary
  • OBEventResourceUpdate2
    • UML Diagram
    • Data Dictionary
  • OBEventConsentAuthorizationRevoked1
    • UML Diagram
    • Notes
    • Data Dictionary
  • OBEventAccountAccessConsentLinkedAccountUpdate1
    • UML Diagram
    • Notes
    • Data Dictionary
• Usage Examples
  • Poll Only
    • POST Events Request
    • POST Events Response
  • Acknowledge Only
    • POST Events Request
    • POST Events Response
  • Poll and Acknowledge With Errors
    • POST Events Request
    • 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	accounts fundsconfirmations	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

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern
OBEventPolling1	1..1	OBEventPolling1		OBEventPolling1
maxEvents	0..1	OBEventPolling1/maxEvents	Maximum number of events to be returned. A value of zero indicates the ASPSP should not return events even if available	xs:int
returnImmediately	0..1	OBEventPolling1/returnImmediately	Indicates whether an ASPSP should return a response immediately or provide a long poll	xs:boolean
ack	0..n	OBEventPolling1/ack	An array of jti values indicating event notifications positively acknowledged by the TPP	Max128Text
setErrs	0..1	OBEventPolling1/setErrs	An object that encapsulates all negative acknowledgements transmitted by the TPP	xs:anyType
<jti>	0..n	OBEventPolling1/setErrs/<jti>	A event notification error object entitled using the jti of the event notification	OBEventError1
err	1..1	OBEventPolling1/setErrs/<jti>/err	A value from the IANA "Security Event Token Delivery Error Codes" registry that identifies the error as defined here (opens new window)	Max40Text
description	1..1	OBEventPolling1/setErrs/<jti>/description	A human-readable string that provides additional diagnostic information	Max256Text

Aggregated Polling - Response

The OBEventPollingResponse1 will be used as the response payload for:

• POST /events

UML Diagram

Data Dictionary

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern
OBEventPollingResponse1	1..1	OBEventPollingResponse1		OBEventPollingResponse1
moreAvailable	1..1	OBEventPollingResponse1/moreAvailable	A JSON boolean value that indicates if more unacknowledged event notifications are available to be returned.	xs:boolean
sets	1..1	OBEventPollingResponse1/sets	A JSON object that contains zero or more nested JSON attributes. If there are no outstanding event notifications to be transmitted, the JSON object SHALL be empty.	xs:anyType
<jti>	0..n	OBEventPollingResponse1/sets/<jti>	An object named with the jti of the event notification to be delivered. The value is the event notification, expressed as a string. The payload of the event should be defined in the OBEventNotification2 format.	xs:string

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

Name	Occurrence	XPath	EnhancedDefinition	Class	Codes	Pattern
OBEventNotification2	OBEventNotification2			OBEventNotification2
iss	1..1	OBEventNotification2/iss	Issuer.	xs:anyURI
iat	1..1	OBEventNotification2/iat	Issued At.	xs:int
jti	1..1	OBEventNotification2/jti	JWT ID.	Max128Text
aud	1..1	OBEventNotification2/aud	Audience.	Max128Text
sub	1..1	OBEventNotification2/sub	Subject.	xs:anyURI
txn	1..1	OBEventNotification2/txn	Transaction Identifier. A unique identifier for the transaction. ASPSPs may populate this field with the x-fapi-transaction-id of the api operation that lead to the change, or populate it with the same value as jti	Max128Text
toe	1..1	OBEventNotification2/toe	Time of Event.	xs:int
events	1..1	OBEventNotification2/events	Events.	OBEvent2
urn:uk:org:openbanking:events:resource-update	0..1	OBEventNotification2/events/urn:uk:org:openbanking:events:resource-update	Resource-Update Event.	OBEventResourceUpdate2
urn:uk:org:openbanking:events:account-access-consent-linked-account-update	0..1	OBEventNotification2/events/urn:uk:org:openbanking:events:account-access-consent-linked-account-update	An event that indicates an account linked to a consent has move in/out of scope of the consent.	OBEventAccountAccessConsentLinkedAccountUpdate1
urn:uk:org:openbanking:events:consent-authorization-revoked	0..1	OBEventNotification2/events/urn:uk:org:openbanking:events:consent-authorization-revoked	An event that indicates a consent resource has had its authorisation revoked.	OBEventConsentAuthorizationRevoked1

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

Name	Occurrence	XPath	Enhanced Definition	Class	Codes	Pattern
OBEventSubject1				OBEventSubject1
subject_type	1..1	OBEventSubject1/subject_type	Subject type for the updated resource.	Max128Text	http://openbanking.org.uk/rid_http://openbanking.org.uk/rty
http://openbanking.org.uk/rid	1..1	OBEventSubject1/http://openbanking.org.uk/rid	Resource Id for the updated resource.	Max128Text
http://openbanking.org.uk/rty	1..1	OBEventSubject1/http://openbanking.org.uk/rty	Resource Type for the updated resource.	Max128Text
http://openbanking.org.uk/rlk	1..n	OBEventSubject1/http://openbanking.org.uk/rlk	Resource links to other available versions of the resource.	OBEventLink1
version	1..1	OBEventSubject1/http://openbanking.org.uk/rlk/version	Resource version.	Max10Text
link	1..1	OBEventSubject1/http://openbanking.org.uk/rlk/link	Resource link.	xs:anyURI

OBEventResourceUpdate2

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

UML Diagram

Data Dictionary

Name	Occurrence	XPath	Enhanced Definition	Class	Codes	Pattern
urn:uk:org:openbanking:events:resource-update			An event that indicates a resource has been updated.	OBEventResourceDescriptor1
subject	1..1	urn:uk:org:openbanking:events:resource-update/subject	The subject of the event.	OBEventSubject1

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

Name	Occurrence	XPath	Enhanced Definition	Class	Codes	Pattern
urn:uk:org:openbanking:events:consent-authorization-revoked			An event that indicates a consent resource has had its authorisation revoked.	OBEventConsentAuthorizationRevoked1
reason	0..1	urn:uk:org:openbanking:events:consent-authorization-revoked/reason	Reason for the Consent Authorization Revoked event.	OBExternalEventConsentAuthorizationRevokedReason1Code
subject	0..1	urn:uk:org:openbanking:events:consent-authorization-revoked/subject	The subject of the event.	OBEventSubject1

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

Name	Occurrence	XPath	Enhanced Definition	Class	Codes	Pattern
urn:uk:org:openbanking:events:account-access-consent-linked-account-update			An event that indicates an account linked to a consent has move in/out of scope of the consent.	OBEventAccountAccessConsentLinkedAccountUpdate1
reason	0..1	urn:uk:org:openbanking:events:account-access-consent-linked-account-update/reason	Reason for the Account Access Consent Linked Account Update event.	OBExternalEventAccountAccessConsentLinkedAccountUpdateReason1Code
subject	1..1	urn:uk:org:openbanking:events:account-access-consent-linked-account-update/subject	The subject of the event. This indicates the account that has been updated. (The sub claim for the event should be used to indicate the affected account-access-consent)	OBEventSubject1

Usage Examples

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

Poll Only

POST Events Request

POST /events HTTP/1.1

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

{
  "returnImmediately": true
}

POST Events Response

POST /events 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 /events HTTP/1.1

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

POST Events Response

POST /events HTTP/1.1

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

{
  "sets": { }
}

Poll and Acknowledge With Errors

POST Events Request

POST /events 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 /events HTTP/1.1

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

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

Event Notification for Account Switching

When an account that a TPP has access to is switched using CASS, the ASPSP may send an event to indicate that the account is undergoing a switch.

The urn:uk:org:openbanking:events:account-access-consent-linked-account-update event is used to indicate this.

If the event is sent when a switch is started, the reason claim should be populated with the value UK.CASS.SwitchStarted. If the event is sent to indicate that the switch was cancelled or failed, the reason claim should be populated with the value UK.CASS.NotSwitched. If the event is sent when a switch is complete, the reason claim should be populated with the value UK.CASS.SwitchCompleted.

The sub claim references the URL of the account-access-consent that gives the TPP access to the account. The subject claim references the actual account that has switched.

In the example below, the account 90200 has just started a switch. The account was linked to an account-access-consent with an id of aac-1234-007

{
  "iss": "https://examplebank.com/",
  "iat": 1516239022,
  "jti": "b460a07c-4962-43d1-85ee-9dc10fbb8f6c",
  "sub": "https://examplebank.com/api/open-banking/v3.1/aisp/account-access-consents/aac-1234-007",
  "aud": "7umx5nTR33811QyQfi",
  "events": {
    "urn:uk:org:openbanking:events:account-access-consent-linked-account-update": {
      "subject": {
        "subject_type": "http://openbanking.org.uk/rid_http://openbanking.org.uk/rty",
        "http://openbanking.org.uk/rid": "90200",
        "http://openbanking.org.uk/rty": "accounts",
        "http://openbanking.org.uk/rlk": [{
            "version": "v3.1",
            "link": "https://examplebank.com/api/open-banking/v3.1/aisp/accounts/90200"
          }
        ]
      }
      }
   },
  "txn": "dfc51628-3479-4b81-ad60-210b43d02306",
  "toe": 1516239022
}