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

# Troubleshoot Webhook Deliveries

> Diagnose the most common webhook problems: signatures that never match, failed deliveries, missing events, and duplicates.

Start in the delivery log at **Workspace Settings** > **Integrations** > **Webhooks** > **Delivery log**. Click **Show details** on the failing row — the response body and error message usually identify the cause on their own.

## Common symptoms

| Symptom                                     | Likely cause                                          | Fix                                                                                                 |
| ------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Signature never matches                     | You hashed re-serialized JSON instead of the raw body | Capture the raw body before JSON parsing. See [Verify signatures](/webhooks/verify-signature).      |
| Signature never matches, raw body confirmed | The secret was rotated and your config is stale       | Copy the current secret from the settings page                                                      |
| Status **Failed**, no status code           | Edplay could not reach you, or TLS failed             | Check the endpoint is public and the certificate is valid and trusted                               |
| Status **Failed** with `500`                | Your handler threw                                    | Check the expanded row's response body, then your own logs                                          |
| Deliveries time out under load              | Real work is happening inside the request             | Enqueue and return `200` immediately                                                                |
| Nothing arrives at all                      | Deliveries paused, or no events selected              | Check **Deliveries active** and the event checkboxes                                                |
| Test event works, real events never arrive  | Subscribed to the wrong event                         | `course.completed` only fires on completion. Select `course.progress_updated` for partial progress. |
| Same event processed twice                  | A retry after a slow `2xx`                            | Make your handler idempotent                                                                        |
| Rows stuck on **Pending**                   | The delivery has not settled yet                      | Refresh after a few seconds                                                                         |

## Diagnosing in detail

<AccordionGroup>
  <Accordion title="My signature check always fails" icon="shield-halved">
    In order of likelihood:

    1. **You are hashing the wrong bytes.** JSON middleware parses and discards the raw body. Hash the raw bytes exactly as received, before anything parses them.
    2. **Your secret is stale.** Rotating invalidates the previous secret immediately, with no overlap. Copy the current value from the settings page.
    3. **You are hashing the `Timestamp` header too.** It is not part of the signature.
    4. **Encoding mismatch.** The signature is lowercase hex, not base64.
  </Accordion>

  <Accordion title="Deliveries fail with no HTTP status" icon="plug-circle-xmark">
    No status code means Edplay never got a response. Check that:

    * the URL is publicly reachable, not `localhost` or a private IP range;
    * the TLS certificate is valid, unexpired, and publicly trusted, since self-signed certificates fail;
    * your firewall is not blocking Edplay's servers;
    * your endpoint responds within 3 seconds.
  </Accordion>

  <Accordion title="I am missing events" icon="inbox">
    Events are dropped, not queued, in these cases:

    * **Deliveries active** was off when the event happened.
    * All three delivery attempts failed. Edplay does not redeliver afterwards.
    * The event type is not selected under **Events**.

    For any gap longer than a couple of minutes, backfill through the API rather than waiting for a redelivery that will not come.
  </Accordion>

  <Accordion title="I receive the same event more than once" icon="copy">
    This is expected. A retry can deliver an event you already processed, for example when you returned `200` just after the 3-second limit. `course.progress_updated` also fires repeatedly by design.

    Deduplicate on `user.id` plus `course.id` plus `occurred_at`, or make your write naturally idempotent.
  </Accordion>
</AccordionGroup>

## Still stuck?

Open the failing row in the delivery log and copy its **UUID**, then send that and the approximate timestamp to [dev@edplay.ai](mailto:dev@edplay.ai). That is enough for us to trace the call end to end.