## 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.

```text
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