Setup
The purpose of webhooks is to notify, in real-time, your application when a particular event occurs in Qonto.
Registering to a webhook event type
You can register to a webhook event type, by calling the POST /v2/webhook_subscriptions endpoint.
By doing so, Qonto will call your callback_url each time there is a new event of the type you registered to.
In order to avoid having your server being overloaded with too many requests, we recommend you to register to only relevant events for your use case.
Please note that Qonto will not send you the events that occurred before you registered to the webhook event type. If you’re interested into these events, please use the HTTP endpoints.
Callback URL
Your callback_url must be publicly accessible and will have to acknoledge the webhook with a 2xx HTTP code.
Qonto will wait for your server to acknowledge the webhook for a maximum of 1 second.
In order to reduce your response time and avoid receiving webhook multiple times, we advise you to store the webhook in a queue system and process it asynchronously.
The callback_url will be called with a POST request containing a X-Qonto-Signature header.
This header contains the HMAC-SHA256 signature of the payload, which you can use to verify that the webhook is coming from Qonto.
The signature header follows the format t={timestamp},v1={signature}.
Verification steps:
- Extract the timestamp and signature from the signature header
- Recreate the signed payload:
{timestamp}.{raw_request_body} - Compute HMAC-SHA256 of the signed payload using your webhook secret as the key
- Compare the computed signature with the one in the header
Test data to validate your signature implementation:
- Payload received:
{"test":"data"} X-Qonto-Signatureheader:t=1704110400,v1=56aff06dc227db80d6568a5070f912c601c31f20451745d257cbc0b5dfa93805- Secret:
test-secret
Retries
If your server does not acknowledge the webhook in less than 1 second, Qonto will consider it as failed and will retry it later. Webhooks are retried with an exponential backoff, for a few days, until it is acknowledged by your server with a 2xx HTTP code.