fraud agent cannot parse chargeback webhook payload
Makes chargeback webhook parsing resilient with pinned versioned schemas, tolerant parsing, and quarantine for bad payloads. Use when the agent crashes on unexpected webhook shapes. Not for provider outages or missing webhooks.
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.
fraud agent cannot parse chargeback webhook payloadUse 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
- Capture the raw payload that failed, bytes intact. Verify: you can replay the exact bytes locally.
- Diff it against your pinned schema version to find what changed. Verify: the diff names the added, removed, or renamed field.
- 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.
- Quarantine anything that still fails: store the raw payload, alert once, and keep consuming. Verify: the consumer keeps advancing past the bad message.
- 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