GUIDE

Webhook breaking-change checklist

A consumer-side review before a payload change reaches production.

Check structure before values

  1. Removed paths your parser reads.
  2. Scalar type changes such as number to string.
  3. Object, array, and scalar shape changes.
  4. New null values where code assumes non-null.
  5. Nested paths moved to a different parent.
  6. Array item shapes and empty-array ambiguity.
  7. Strict decoders that reject additive fields.

Turn the sample into a regression fixture

Keep a sanitized old and new fixture in the consumer repository. Run the real parser or handler against the new fixture and assert the business output—not only the JSON shape.

Know the limit of two samples

Samples cannot establish the full set of required fields, enum values, or conditional variants. Provider documentation and production-safe contract tests remain necessary.

Scan two payloads locally