Skip to main content
If you haven’t yet confirmed that your subscription receives events, start with Test with webhook.site. It isolates the Qonto side from your own endpoint and makes failures much easier to narrow down.
Check, in order:
  • Your callback_url is publicly reachable over HTTPS (no localhost, no private network, valid certificate).
  • Your server accepts POST requests and responds with a 2xx status within 1 second.
  • The subscription exists and is active: GET /v2/webhook_subscriptions.
  • The event type you subscribed to matches what you’re trying to trigger (see Supported webhooks).
Still nothing? Point the subscription at a webhook.site URL to confirm whether the issue is on Qonto’s side or your endpoint’s.
The X-Qonto-Signature header follows the format t={timestamp},v1={signature}. Common mistakes:
  • Re-serializing the body. The signed payload is {timestamp}.{raw_request_body} — use the raw bytes as received, not a re-serialized JSON string. Whitespace and key ordering matter.
  • Wrong secret. Use the secret returned when the subscription was created, not your API key.
  • Truncated timestamp or signature. Split the header on , and then on = — don’t regex past the comma.
Validate your implementation against the test vector documented in Setup before suspecting anything else.
This means your endpoint did not acknowledge the webhook with a 2xx within 1 second, so Qonto retried it.
  • Acknowledge immediately with a 2xx, then process asynchronously (queue the payload and return).
  • Make your handler idempotent: retries can also happen after transient errors, so processing the same event twice must be safe.
Webhooks are retried with exponential backoff for a few days. After that, delivery is abandoned for that event.
  • Check that your subscription still exists with GET /v2/webhook_subscriptions.
  • Confirm your endpoint is currently responding with 2xx within 1 second.
  • Trigger a new event (see the webhook.site guide for reliable triggers) to verify delivery resumed.
There is one subscription per event type. Listing subscriptions via GET /v2/webhook_subscriptions shows which types you’re registered to. Create additional subscriptions for any other type you need — the full catalogue is under Supported webhooks.