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

# Troubleshoot

> Diagnose and fix common webhook delivery issues

<AccordionGroup>
  <Accordion title="My endpoint was automatically disabled">
    Allo disables endpoints that fail continuously for 5 days. To fix:

    1. Check the delivery history in [Settings > Webhooks](https://web.withallo.com/settings/webhooks) to understand why deliveries failed.
    2. Fix the underlying issue (URL changed, server down, authentication error, etc.).
    3. Re-enable the webhook from [Settings > Webhooks](https://web.withallo.com/settings/webhooks).
    4. Use the **Recover** option to replay missed events.
  </Accordion>

  <Accordion title="Deliveries show 4xx or 5xx errors">
    Check these common causes:

    * **401/403**: Your endpoint requires authentication. Webhook requests do not include your API key — they use [signature verification](/en/v2/api-reference/webhooks/verifying-signatures) instead.
    * **404**: The webhook URL is incorrect or your server's routing does not match.
    * **500**: Your handler is throwing an error. Check your server logs.
    * **Firewall/WAF**: Your firewall or web application firewall may be blocking the requests. Allow incoming POST requests to your webhook path.
  </Accordion>

  <Accordion title="Signature verification fails">
    Common causes:

    * **Parsed body**: You must use the **raw request body** for verification. If your framework automatically parses JSON and you re-serialize it, whitespace differences will break the signature. Use `express.raw()` in Node.js or `request.get_data()` in Flask.
    * **Wrong secret**: Ensure you are using the correct `whsec_...` signing secret for this specific endpoint.
    * **Clock skew**: Your server's clock must be within 5 minutes of the actual time. Verify NTP is running on your server.
    * **Middleware modification**: Proxies or middleware that modify request headers or body will invalidate the signature.
  </Accordion>

  <Accordion title="I'm not receiving events">
    Check the following:

    1. **Webhook is enabled**: Go to [Settings > Webhooks](https://web.withallo.com/settings/webhooks) and verify the webhook is enabled.
    2. **Topics match**: Verify the event types you expect are selected in the webhook configuration.
    3. **Delivery history**: Check the delivery history in your webhook settings — events may be failing silently.
    4. **URL is reachable**: Ensure your endpoint is publicly accessible over HTTPS. Use the [test feature](/en/v2/api-reference/webhooks/testing) to verify.
  </Accordion>

  <Accordion title="I'm receiving duplicate events">
    This is expected behavior. Allo uses at-least-once delivery, so events may be delivered more than once.

    Implement idempotency using the `webhook-id` header as a deduplication key. See [Best practices](/en/v2/api-reference/webhooks/best-practices#implement-idempotency).
  </Accordion>

  <Accordion title="Deliveries are timing out">
    Your endpoint must respond within 20 seconds. If your processing takes longer:

    1. Return `200` immediately upon receiving the request.
    2. Queue the event for background processing.
    3. Process the event asynchronously (e.g., using a message queue or background job).

    See [Best practices — Respond quickly](/en/v2/api-reference/webhooks/best-practices#respond-quickly).
  </Accordion>
</AccordionGroup>

## Need help?

<CardGroup cols={2}>
  <Card title="Contact support" icon="headset" href="mailto:support@withallo.com">
    Reach out to our support team
  </Card>

  <Card title="API reference" icon="book" href="/en/v2/api-reference/webhooks/overview">
    Browse the full webhook documentation
  </Card>
</CardGroup>