> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qonto.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose common webhook delivery, signature and retry issues.

> [!TIP]
>
> If you haven't yet confirmed that your subscription receives events, start with [Test with webhook.site](https://docs.qonto.com/guides/webhooks/testing.md). It isolates the Qonto side from your own endpoint and makes failures much easier to narrow down.

> **I don't receive any webhook on my endpoint**
>
> 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`](https://docs.qonto.com/api-reference/business-api/webhooks/list-webhook-subscriptions).
> * The event type you subscribed to matches what you're trying to trigger (see [Supported webhooks](https://docs.qonto.com/guides/webhooks/supported-events.md)).
>
> Still nothing? Point the subscription at a [webhook.site](https://docs.qonto.com/guides/webhooks/testing.md) URL to confirm whether the issue is on Qonto's side or your endpoint's.

> **Signature verification fails**
>
> 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](https://docs.qonto.com/guides/webhooks/setup.md#callback-url) before suspecting anything else.

> **I receive the same event multiple times**
>
> 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 stopped coming**
>
> 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`](https://docs.qonto.com/api-reference/business-api/webhooks/list-webhook-subscriptions).
> * Confirm your endpoint is currently responding with `2xx` within 1 second.
> * Trigger a new event (see the [webhook.site guide](https://docs.qonto.com/guides/webhooks/testing.md) for reliable triggers) to verify delivery resumed.

> **I only receive some event types**
>
> There is **one subscription per event type**. Listing subscriptions via [`GET /v2/webhook_subscriptions`](https://docs.qonto.com/api-reference/business-api/webhooks/list-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](https://docs.qonto.com/guides/webhooks/supported-events.md).