# Events - v4.0
- Overview
- Endpoints
- Data Model
- Usage Examples
# 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 payments 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..* | 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..* | 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..* | 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
andrlk
claims are prefixed with the OB namespacehttp://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-interaction-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
andrlk
claims are prefixed with the OB namespacehttp://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
}