Webhook broke after a provider change, or you can't parse the error body? Handling webhook drift

Two webhook problems catch teams off guard: a webhook that worked for months suddenly breaks because the provider changed the payload, and an error response you can't make sense of because it's a structured application/problem+json document you're treating as a blob.

Payload schema drift

You built the handler against the payload as it looked then. Months later the provider renames a field, nests it differently, or drops it — schema drift — and your parser, which assumed the old shape, breaks. Nothing changed on your side, which is what makes it confusing.

1. Pin the webhook API version where the provider supports it, so payload shape changes are opt-in, not surprise.
2. Fail loud on a missing expected key. If a field you depend on is absent, raise a clear error — don't silently process a half-parsed payload and corrupt downstream state.
3. Validate the payload against a schema at the boundary, so drift is caught immediately with a precise message.

Parsing application/problem+json (RFC 9457)

For agents consuming webhooks and APIs

An agent that assumes a fixed payload shape breaks silently on drift, and one that ignores a problem+json body throws away the diagnosis it was handed. diagnose_infra_error returns the webhook-drift family with the fix — pin the version, fail loud on missing keys, parse the problem-details pointer:

diagnose_infra_error({error: "application/problem+json rfc9457 webhook missing field"})
// → { family: "webhook-drift",
//      fix: "parse the RFC 9457 problem-details (errors[].pointer); pin the webhook API version; fail loud on missing keys" }