The Basics

Webhooks allow your Application to receive information about events relating to your integration as they occur. They provide a more responsive and more scalable alternative to polling (periodically checking) for updates.

Tapico pushes notifications (Webhook events) to your application with JSON payloads via HTTPS.

Webhooks are Region-specific. That means notifications arising from activity in a Tapico region will be triggered and dispatched to your application from that region.

Use Cases

Webhooks are useful for use cases that involve performing some action in response to asynchronous events, for example:

• Fetching Open Finance data in the background after a user has confirmed access consent.
• Updating your system once a payment instruction has been authorised and dispatched to the user's bank.

Security

Tapico 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 Tapico.

Webhook Setup

1. Configuring Webhooks

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.