Open Finance Webhook Events
The table below gives descriptions for each of the Open Finance webhook events your application can subscribe to.
These are events generated by the Platform itself in relation to Account Access and Payment consent system events.
Open Finance webhooks are Region-specific. That means notifications arising from activity in a FNZ region will be triggered and dispatched to your application from that region.
Prerequisites
Security
Open Finance webhooks use HMAC signatures as an added security measure. In order to receive webhooks, your application requires a signing a signing secret which can be provisioned via: Application → Basic Details → Signing Secret.
What is HMAC?
HMAC (Hash-based Message Authentication Code) is a type of a message authentication code (MAC) that is acquired by executing a cryptographic hash function on the data (that is) to be authenticated and a secret shared key. As with any MAC, it may be used to simultaneously verify both the data integrity and authenticity of a message.
Each webhook request will include a signature in the header: tapico-signature
.
Verifying the signature involves taking the webhook's request body, applying the SHA-256 hash function to it with the signing secret as the hash key. You can then compare the resulting hash to the signature in tapico-signature
to verify that the payload has not been tampered with, and that it originated from FNZ.
Webhook Setup
1. Configuring Webhooks
Open Finance webhooks are managed via Application → Webhooks.
This supports the following functionality:
- Add or remove webhooks
- Enable or disable a webhook
- Set or modify the event subscriptions for webhook
- Monitor existing webhooks including logs of notification attempts
2. Testing Your Webhook
Once you have set up your webhook you can test that it is working properly via the Send Test Event function.
This allows you to generate a mock payload for one of the Event Types your webhook is subscribed to and dispatch it to your Target URL:
Test Events
You can differentiate between actual webhook events and test events. Test events will contain the root property
"test": true
, whereas actual events will not.
Webhook Retries
In the event of a webhook notification failure we will automatically resend the requests multiple times. The timing of these retries follows an exponential delay algorithm. Responses that do not return 2XX
status codes are treated as a failure.
The status of notifications and their attempts can be viewed in: Application → Webhooks → Select webhook > Select Event.
Account Access Consent Event Types
Webhook events that are related to the account-access-consent
endpoint.
Event - Account Access Consent | Description |
---|---|
AccountAccessConsent.Approved | The account-access-consent request has been approved by the end-user with their account servicer. Now you can request account information. |
AccountAccessConsent.DataFetched | Data has been refreshed from the account servicer's system and is available via the relevant API endpoint. |
AccountAccessConsent.Revoked | The end user will always have the ability to revoke the consent. If this happens you will no longer have access to the user's data set. The end-user will have to give their consent again to restore access for your app. |
AccountAccessConsent.ReconfirmationRequired | The account-access-consent needs to be reconfirmed in order to continue pulling data from the account servicer's system. This webhook will be triggered daily starting daysBeforeExpirationNotification days before the expiryDate , until the reconfirmation takes place and a new expiry date will be set. |
Payment Instruction Event Types
Webhook events that are related to the payment-instruction
endpoint.
Event - Payment Instruction | Description |
---|---|
PaymentInstruction.Dispatched | The payment-instruction has been approved by the end-user and dispatched to the account servicer for execution. |
PaymentInstruction.Failed | The payment-instruction has failed. |
PaymentInstruction.Rejected | The payment-instruction has been rejected by the account servicer. |
Updated 5 months ago