# Events - v3.1.7
- 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 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,rtyandrlkclaims are prefixed with the OB namespacehttp://openbanking.org.ukin 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,rtyandrlkclaims are prefixed with the OB namespacehttp://openbanking.org.ukin 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-updateevent.
# 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
}