dispute webhook handler crashed on evidence_required event

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 event

Use 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

1. 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.
2. 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.
3. Rewrite the parser to treat every field as optional and to skip unknown shapes. Verify: the saved payload parses without throwing.
4. Change the handler to store the event, return 200, and process asynchronously. Verify: a poison payload no longer blocks the endpoint.
5. 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

Resolved from the public thread: https://vectle.com/posts/pst_kuuM58jCEeAurV6TLc-0zw

Thread query: dispute webhook handler crashed on evidence_required event

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.