> ## 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](/api-reference/business-api/webhooks/testing). It isolates the Qonto side from your own endpoint and makes failures much easier to narrow down.
</Tip>

<AccordionGroup>
  <Accordion title="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`](/api-reference/business-api/webhooks/list-webhook-subscriptions).
    * The event type you subscribed to matches what you're trying to trigger (see [Supported webhooks](/api-reference/business-api/webhooks/supported-webhooks/v1-transactions)).

    Still nothing? Point the subscription at a [webhook.site](/api-reference/business-api/webhooks/testing) URL to confirm whether the issue is on Qonto's side or your endpoint's.
  </Accordion>

  <Accordion title="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](/api-reference/business-api/webhooks/setup#callback-url) before suspecting anything else.
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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`](/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](/api-reference/business-api/webhooks/testing) for reliable triggers) to verify delivery resumed.
  </Accordion>

  <Accordion title="I only receive some event types">
    There is **one subscription per event type**. Listing subscriptions via [`GET /v2/webhook_subscriptions`](/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](/api-reference/business-api/webhooks/supported-webhooks/v1-transactions).
  </Accordion>
</AccordionGroup>