dispute webhook handler crashed on evidence_required event
Hardens a dispute webhook handler that crashes on evidence_required events: null-safe parsing, async processing after acknowledgement, and a dead-letter queue for poison payloads. Use when one event type kills the handler while others pass. Not for signature failures or missing events.
TL;DR
A crash on the evidence_required event usually means the handler assumed fields that this event type does not carry. Capture the failing payload, make parsing null-safe and tolerant of missing fields, acknowledge then process asynchronously, and route poison payloads to a dead-letter queue.
dispute webhook handler crashed on evidence_required eventUse this when
- One event type kills the handler while others pass.
- The crash started when dispute events began arriving.
- Retries keep crashing on the same payload.
Not for this skill when
- The signature check fails. That is a verification problem.
- Events never arrive. That is a subscription problem.
Steps
- Pull the exact payload that crashed from your logs or the provider's delivery history. Verify: you have the full body that triggered the crash.
- Find the field access that threw: usually a nested object that is null on this event type. Verify: you can reproduce the crash locally with the saved payload.
- Rewrite the parser to treat every field as optional and to skip unknown shapes. Verify: the saved payload parses without throwing.
- Change the handler to store the event, return 200, and process asynchronously. Verify: a poison payload no longer blocks the endpoint.
- Route unparseable payloads to a dead-letter queue with an alert. Verify: a malformed event lands in the queue and pages someone.
Variant phrasings
webhook handler crash dispute event
Common search order.
evidence_required event handler error
Event-first wording.
chargeback webhook 500 handler
Status-code wording.
Compatibility: Any dispute webhook provider. Event shapes vary by type; handlers must parse defensively across the whole event catalog.
Why it happens
Handlers get written against the first event type the team sees, usually a payment event, and the dispute events arrive months later with a different shape. One unguarded nested access is enough to 500 every dispute notification until someone notices.
Edge cases / pitfalls
- A 200 after a crash in async processing still loses the event. Persist first, then acknowledge.
- Schema registries help, but providers add fields without notice. Unknown fields must be ignored, not rejected.
- Test with real dispute payloads from the dashboard, not hand-written fixtures. Fixtures drift.
- Alert on the dead-letter queue size. A silent queue is a silent loss of events.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_kuuM58jCEeAurV6TLc-0zw