Webhook contract changes can break clients that are still processing older deliveries. Version payload structure and meaning, then test the transition before retiring a contract that active consumers still depend on.
Compatibility includes event semantics
Webhook contract versioning manages changes to event fields, types, identity rules, and outcome meaning. Renaming a required customer key is a structural break. Changing whether an amount is gross or net is a semantic break even when its type stays numeric.
For a proposed producer, document each supported version and how subscribers select or discover it. Keep event identity stable under the documented redelivery behaviour. Record the version with durable receipts so old payloads can be interpreted correctly during replay.
Do not silently reinterpret a historical payload through the latest schema. Old deliveries and queued events may outlive a deployment. Use an intentional tested adapter or a clear unsupported-version disposition.
Test a fictional identifier migration
Version one sends a customer reference unique within an account. Version two introduces an explicit account namespace. Existing clients cannot safely receive the new representation without a compatible mapping or planned migration.
The producer tests old and new consumers, duplicate deliveries, and replay of a version-one event after the version-two release. The expected customer relationship must remain correct, not merely parse as valid JSON.
| Contract change | Compatibility question |
|---|---|
| Optional field added | Does omission preserve old behaviour? |
| Required identifier changed | How do existing consumers adapt? |
| New event type | Can old subscribers ignore it safely? |
| Meaning of a status changed | Is a new version required? |
| Historical replay | Which contract interprets the stored event? |
Include representative failure fixtures and a migration note showing effective dates, consumer obligations, and retirement conditions. A release note saying “payload improved” is not a usable contract.
Make retirement observable
Track consumer version usage through appropriate operational metadata and define the supported migration window. Long-running queues and customer-managed deployments may need more time than an internal application.
Maintaining several versions adds code and test burden. Avoid indefinite adapters that conceal incompatible domain assumptions. Retire deliberately with evidence that supported clients have migrated or an explicit policy for the remaining cases.
This versioning design is proposed. The voice integration case study establishes related backend experience. Compare agent tool-contract compatibility for another consumer-contract boundary.
Webhook versioning FAQ
Is adding a field always compatible?
No. Consumer validation and the field’s behavioural effect determine compatibility.
Should old events use the newest interpretation?
Only through an explicit tested migration that preserves their intended meaning.
What proves a client migration is ready?
Compatible fixtures, documented selection and replay behaviour, observable usage, and a defined recovery path.