[

Debug Lumx webhook delivery

]

Setup and testing

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.

// PROMPT

{ "type": "INDIVIDUAL", "name": "William Default", "taxId": "100.100.100-01", "birthDate": "1990-01-01" }

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 retries up to eight times 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.

  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.

TALK TO OUR TEAM

Ready to transform your business with stablecoins?

Discover how our infrastructure can seamlessly integrate stablecoins into your financial operations quickly, securely, and efficiently.

©2026. All rights reserved.

LUMX SOCIEDADE PRESTADORA DE SERVIÇOS DE ATIVOS VIRTUAIS LTDA., a private legal entity, enrolled with the CNPJ/MF under No. 42.887.120/0001-00 ("Lumx"), acts as a virtual asset service provider and is in the process of adapting to the regulatory regime for Virtual Asset Service Provider Companies (SPSAV), pursuant to Central Bank of Brazil (BCB) Resolution No. 520/2025, currently being subject to the transition regime set forth in Article 88 thereof.


Lumx US OP LLC ("Lumx") is a financial technology and payments infrastructure company. Lumx US OP LLC is a Money Service Business (MSB) registered with the Financial Crimes Enforcement Network (FinCEN) (MSB #31000316459619). Lumx is not a state-licensed money transmitter and does not, in its own capacity, engage in the provision of regulated money transmission services. All such regulated activities are conducted exclusively through, and under the licenses of, duly authorized financial-institution partners.


Lumx is not a bank, financial institution, payment institution, or custodian of client funds. Certain services made available through the Platform may be provided by duly authorized and regulated third-party partners, in accordance with applicable laws and regulations.

Please refer to Lumx’s Terms of Use and Privacy Notice for further information regarding the conditions governing the use of the Platform and the processing of your personal data.