Open Banking Consent Events
What is an Open Banking Event?
Our Open Banking (OB) event service allows customers to meet regulatory requirements concerning end-user notifications or to provide other functionality dependent on knowing the state of user consent to collect and use data.
To comply with Subdivision 4.3.5 of the CDR Rules, Australian (AU) OB customers must send notifications “in writing otherwise than through the CDR consumer’s dashboard” to end users whenever consent is granted, amended or revoked (CDR Receipts) as well as ongoing notifications for ongoing consents.
We recommend AU OB customers comply with this requirement by sending an SMS or email to end-users. The rules require that notifications must contain details of the consent, including the requested data, use of the data, time of grant and scheduled expiry, data access frequency, data provider name (e.g., ABC bank), the data recipient name and details of any disclosure consents (such as to trusted advisors or of CDR Insights).
We provide these events to customers of all OB-supported regions. Currently, we do not provide these notifications in PDF format.
Note: OB onboarding must be completed for the relevant OB region before subscribing to the events service.
Consent Status Updates Event
The consent status updates event - OB_CONSENT - occurs when consent is created, amended, expired, or revoked. Information from this event can be used to send a CDR Receipt to AU OB end users (see CDR Rules 4.18, 4.18A and 4.18C). Customers from other OB-supported regions can use this information per their business needs.
Event Subscription
Subscribe to the OB_CONSENT event using the Subscribe Event service and provide the callback URL where the notifications have to be posted. This is a one-time activity unless and until there is a change to the URL. Note that only one webhooks URL at a time is supported.
Active Consent Updates Event
The active consent updates event - OB_ACTIVE_CONSENT_REMINDER - notifies that an end-user consent is still active and has been - 90 days for the AU region and other OB-supported regions 30, 60, 90, 120, 150, and 180 days - since the last notification or relevant user action. This event can be used to trigger an ongoing notification to AU OB customers (see CDR Rules 4.20).
Event Subscription
The subscribe API service allows to subscribe to the OB_ACTIVE_CONSENT_REMINDER event. Provide the callbackUrl and subscription parameters such as obRegion and notifyDurationDays details in the request body.
| API URL: |
POST /configs/notifications/custom/events/OB_ACTIVE_CONSENT_REMINDER |
Request Body Parameters:
| Attributes | Description | Mandatory | Data Type |
|---|---|---|---|
| callbackUrl | URL to which the notification should be posted. | Yes | String |
| subscription | Object to define the obRegion and notifyDurationDays details. At least one object having both obRegion and notifyDurationDays should be present should be present.Valid Values:
|
Yes | String |
Sample Request Body:
{
"event":{
"callbackUrl":"https://webhook.site/37629a8e-fb37-4351-9d93-cd86f0f11b00",
"subscription":[
{
"obRegion":"US",
"notifyDurationDays":20
},
{
"obRegion":"UK",
"notifyDurationDays":40
},
{
"obRegion":"AU",
"notifyDurationDays":90
}
]
}
}
Response Messages:
| HTTP Status Code | Reason |
|---|---|
| 400 | Y803: notifyDurationDays is required |
| 400 | Y803: obRegion is required |
| 400 | Y800: Invalid value for callbackUrl |
| 400 | Y800: Invalid value for obRegion |
| 400 | Y822: AU cannot be requested for number of days other than 90 days |
| 400 | Y804: Permitted values of notifyDurationDays between 1 – 365 |
| 400 | Y400: Event OB_ACTIVE_CONSENT_REMINDER is already subscribed |
Retrieve Event
Use the API to fetch callbackUrl, obRegion, and notifyDurationDays (all regions) details for the OB_ACTIVE_CONSENT_REMINDER event.
| API URL: |
GET /configs/notifications/custom/events/OB_ACTIVE_CONSENT_REMINDER |
Sample Response:
{
"event": {
"callbackUrl": "https://webhook.site/37629a8e-fb37-4351-9d93-cd86f0f11b00",
"subscription": [
{
"obRegion": "US",
"notifyDurationDays": 20
},
{
"obRegion": "UK",
"notifyDurationDays": 40
},
{
"obRegion": "AU",
"notifyDurationDays": 90
}
]
}
}
Response Messages:
| HTTP Status Code | Reason |
|---|---|
| 400 | Y807: Resource not found |
Update Event
Use the API to update the callbackUrl and subscription parameters - obRegion, and notifyDurationDays details for the OB_ACTIVE_CONSENT_REMINDER event. If the subscription parameter has having multiple objects (i.e, obRegion and notifyDurationDays) then existing value completely replace with latest provided values in PUT API.
| API URL: |
PUT /configs/notifications/custom/events/OB_ACTIVE_CONSENT_REMINDER |
Request Body Parameters:
| Attributes | Description | Mandatory | Data Type |
|---|---|---|---|
| callbackUrl | URL to which the notification should be posted. | Yes | String |
| subscription | Object to define the obRegion and notifyDurationDays details. At least one object having both obRegion and notifyDurationDays should be present should be present.Valid Values:
|
Yes | String |
Sample Request Body:
{
"event":{
"callbackUrl":"https://webhook.site/37629a8e-fb37-4351-9d93-cd86f0f11b00",
"subscription":[
{
"obRegion":"US",
"notifyDurationDays":30
},
{
"obRegion":"AU",
"notifyDurationDays":90
}
]
}
}
Response Messages:
| HTTP Status Code | Reason |
|---|---|
| 400 | Y803: notifyDurationDays is required |
| 400 | Y803: obRegion is required |
| 400 | Y800: Invalid value for callbackUrl |
| 400 | Y800: Invalid value for obRegion |
| 400 | Y822: AU cannot be requested for number of days other than 90 days |
| 400 | Y804: Permitted values of notifyDurationDays between 1 – 365 |
| 400 | Y400: Event OB_ACTIVE_CONSENT_REMINDER is already subscribed |
Unsubscribe Event
Use the API to unsubscribe to the OB_ACTIVE_CONSENT_REMINDER event.
| API URL: |
DELETE /configs/notifications/custom/events/OB_ACTIVE_CONSENT_REMINDER |
Response Messages:
| HTTP Status Code | Reason |
|---|---|
| 400 | Y807: Resource not found |
Event Payload Information
The payload sent to the customer-provided URL has a common structure regardless of the event type. Events are sent asynchronously in small batches - a single payload may contain multiple events.
OB_CONSENTA sample event for consent authorization is as follows:
{
"event":{
"data":{
"consent":[
{
"dataAccessFrequency":"RECURRING",
"consentId":12341234,
"renewal":{
"defaultRenewalDuration":365,
"isReauthorizationRequired":true
},
"providerId":31193,
"consentStatus":"ACTIVE",
"providerAccountId":10107407,
"providerConsentId":"e767574f-296a-4cb2-95e2-f5faf7584e22",
"applicationDisplayName":"Sample application name",
"startDate":"2023-05-17",
"expirationDate":"2024-05-16"
}
]
},
"notificationId":"ab5837ad-168201359",
"info":"OB_CONSENT.CONSENT_CHANGES"
}
}
A sample event for consent revocation is as follows:
{
"event":{
"data":{
"consent":[
{
"dataAccessFrequency":"RECURRING",
"consentId":12341234,
"renewal":{
"defaultRenewalDuration":365,
"isReauthorizationRequired":true
},
"providerId":31193,
"consentStatus":"REVOKED",
"providerAccountId":12340274,
"revokedDate":"2023-05-18",
"providerConsentId":"e767574f-296a-4cb2-95e2-f5faf7584e22",
"applicationDisplayName":"Sample application name",
"startDate":"2023-05-17",
"expirationDate":"2024-05-16"
}
]
},
"notificationId":" ebb967b5-123412345",
"info":"OB_CONSENT.CONSENT_CHANGES"
}
}
OB_ACTIVE_CONSENT_REMINDER
{
"event":{
"data":{
"consent":[
{
"dataAccessFrequency":"RECURRING",
"consentId":12341234,
"renewal":{
"defaultRenewalDuration":365,
"isReauthorizationRequired":true
},
"providerId":31193,
"consentStatus":"ACTIVE",
"providerAccountId":10107407,
"providerConsentId":"e767574f-296a-4cb2-95e2-f5faf7584e22",
"applicationDisplayName":"Sample application name",
"startDate":"2023-05-17",
"expirationDate":"2024-05-16",
"obRegion":"AU",
"notifyDurationDays":20
}
]
},
"notificationId":"recsd8743ad-98283245",
"info":"OB_ACTIVE_CONSENT_REMINDER"
}
}
Note: All timestamps are in universal coordinated time (UTC).
| Event Attributes Name | Description |
|---|---|
| dataAccessFrequency | The frequency, RECURRING or ONE_TIME, at which the system will access user data as part of the account refresh process. Frequency as applicable to the OB-supported region. |
| consentId | The unique identifier for each user-consent. |
| renewal.defaultRenewalDuration | The renewal duration for a given consent. The renewal duration's availability depends on the OB-supported region. For example, it is available for the AU region. |
| renewal.isReauthorizationRequired | Indicates if renewing the consent is required. |
| providerId | The unique identifier for the provider resource associated with the consent. This ID indicates the provider for which the provider account ID is generated by the user. This ID can be dereferenced using the Get Providers API. |
| consentStatus | The consent status, as applicable to the relevant open banking region. Possible values are, REVOKED, ACTIVE, PENDING, and EXPIRED. |
| providerAccountId | The unique identifier for the provider account resource associated with a consent. The ID is created during the account addition process and is made available via the Get Accounts API. |
| scope.titleBody | Text that will be displayed as the titlebody of the consent data cluster. |
| scope.scopeId | A unique identifier of the data cluster scope. |
| scope.title | Text that will be displayed as the title of the particular scope. |
| providerConsentId | Unique internal identifier for the consent and is made available via the Get Provider Accounts API. |
| applicationDisplayName | The OB application name that will be displayed to the end user. |
| startDate | The start date of the consent period. |
| expirationDate | The date the refresh token expires, and the customer has to renew the access before it expires. |
| obRegion | Indicates the OB region, i.e., US, UK, or AU.Note: Available only for the OB_ACTIVE_CONSENT_REMINDER event. |
| notifyDurationDays | The duration since the last notification or relevant user action for the consent. Note: Available only for the OB_ACTIVE_CONSENT_REMINDER event. |
| notificationId | Unique identifier for the notification. |
| info | The info attribute value will either be OB_CONSENT.CONSENT_CHANGES or OB_ACTIVE_CONSENT_REMINDER. |