## TL;DR
The chargeback webhook arrives in a shape the agent does not expect and parsing throws, killing the consumer. Fix: validate against a pinned, versioned schema, parse tolerantly by requiring only the fields you act on, and quarantine unparseable payloads with the raw bytes preserved. One bad payload must never stop the stream.

```text
fraud agent cannot parse chargeback webhook payload
```

## Use this when
- The webhook consumer crashes or drops messages on specific payloads.
- A provider schema change coincides with the first failures.
- Some dispute events process fine while others throw.

## Not for this skill when
- Webhooks never arrive. That is a delivery or subscription problem.
- The payload parses but the values are wrong. That is a mapping problem.

## Steps
1. Capture the raw payload that failed, bytes intact. Verify: you can replay the exact bytes locally.
2. Diff it against your pinned schema version to find what changed. Verify: the diff names the added, removed, or renamed field.
3. Parse tolerantly: require only the fields your logic needs, like dispute id, amount, and status, and ignore the rest. Verify: the failing payload parses after the change.
4. Quarantine anything that still fails: store the raw payload, alert once, and keep consuming. Verify: the consumer keeps advancing past the bad message.
5. Pin the provider's schema version in config and keep a recorded fixture per version for tests. Verify: a schema bump fails a test before it fails production.

## Variant phrasings
### chargeback webhook parse error
Common phrasing.
### webhook payload schema mismatch
Schema-focused search.
### agent crashes on dispute webhook
Crash-focused phrasing.
### dispute webhook payload rejected
Rejection-focused phrasing.

Compatibility: any webhook consumer; the pattern is the same for Stripe, Adyen, Braintree, and processor-specific formats.

## Why it happens
Providers evolve their payloads and parsers get written against one snapshot. Strict parsing turns every provider change into a production incident. Version your fixtures with the provider's changelog date so you know which snapshot you coded against.

## Edge cases / pitfalls
- Renamed fields your logic depends on: map old and new names explicitly during a transition window, and keep the old mapping until the provider confirms the cutover.
- Payloads arriving with unexpected content encoding: normalize before parsing.
- Quarantine queues need their own alerting and replay tooling, or they become a graveyard.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_eHrnLHA5DYvVJnycD-p14Q