> ## Documentation Index > Fetch the complete documentation index at: https://docs.lumx.io/llms.txt > Use this file to discover all available pages before exploring further. # Debug Lumx webhook delivery > A copy-paste prompt that walks the real failure taxonomy of a Lumx webhook endpoint — raw body, rotated secret, replay window, retries, silent drops. Paste this prompt into your coding agent when events are not arriving, or are arriving and failing verification. The agent works through the causes in order, from an unreachable endpoint to a re-serialized body, a prefixed secret, a rotation, and clock skew, and names the one that applies. ## Before you start * One failing delivery from the [Dashboard](https://dashboard.lumx.io): its id, timestamp, and body. ## Prompt ```text Prompt theme={null} You are a senior engineer debugging a Lumx webhook endpoint that is not working. Diagnose before you change anything: the symptom "signature invalid" has four different causes and three of them are not the secret. Ground truth. Read both before changing any code and follow them over any prior knowledge: 1. https://docs.lumx.io/developer/webhooks — the signature scheme, the event catalog, the retry schedule and the delivery IPs. Also read https://docs.lumx.io/llms.txt for the rest of the documentation. 2. https://lumx-docs-public-prod.s3.us-east-1.amazonaws.com/api-production.yaml — the OpenAPI 3.1 spec, for the resource shapes inside the payload. Work through the causes in this order, cheapest first, and report what you ruled out at each step. 1. Nothing arrives at all. Check the endpoint is registered in the Dashboard under Developers → Webhooks, is publicly reachable, and returns 2xx to a bare POST. If the infrastructure filters inbound traffic, confirm the published Lumx delivery IPs are allowed — the same set serves sandbox and production. 2. It arrives and 401s or 403s before your handler. If the endpoint URL carries basic-auth credentials, Lumx extracts them and sends an Authorization header; a proxy that strips or double-handles it breaks delivery before any signature check. 3. Signature fails on every event. The most common cause is a re-serialized body: verification runs over the exact bytes received, so capture the raw body before any JSON parser touches it. Second cause: the secret was used as-is — the whsec_ prefix must be stripped and the remainder base64-decoded before it becomes the HMAC key. 4. Signature fails only since a secret rotation. During a rotation Lumx signs with the old and the new secret for 24 hours, so the header carries a space-delimited list. Code that reads only the first signature fails intermittently for exactly one day. Accept any valid entry. 5. Signature fails only on some events. Suspect the replay window: the signed content is "{webhook-id}.{webhook-timestamp}.{body}" and a clock skew on your side rejects valid events. Log the computed skew before rejecting. 6. Events arrive more than once, or out of order. That is expected. Delivery is attempted up to eight times in total, with growing backoff after any non-2xx, so deduplicate on webhook-id and treat state from GET /transactions/{id} as authoritative over arrival order. 7. Events stop after a while. After the retries are exhausted the message is marked failed and can only be replayed from the Dashboard. Check whether your endpoint was returning non-2xx during a deploy. Constraints: - Do not weaken verification to make events flow, including in sandbox. - Do not claim an event type exists without finding it in the catalog on the docs page. - Log the failure cause; never swallow a rejected event silently. Deliverables: - A diagnosis naming which of the seven causes applied, with the evidence. - The fix, plus a unit test that would have caught it. - A replay script that posts a stored event locally so the next diagnosis needs no live traffic. ``` ## How to use 1. Collect one failing delivery from the Dashboard first — its id, timestamp and body. Debugging from logs alone costs an extra round. 2. Rotate the signing secret yourself if step 4 is the suspect; the agent must not rotate credentials. 3. Keep the replay script in the repo. Every webhook bug after this one is cheaper with it. ## What the prompt builds | **Endpoint** | **What the agent uses it for** | | :- | :- | | `GET /transactions/{id}` | Confirms state when events arrive out of order | ## Related resources Event catalog, signatures, and retries. Transaction types and status progressions. Receive signed events that survive retries and secret rotation. Audit a working Sandbox integration before real money moves. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.