Agent WranglersEVT-3Recommended
Version event payloads
Name each event type and version its payload, and change it only by adding fields, as with the API itself.
How to do it
Use names such as order.shipped. Describe events in the contract, for example in OpenAPI's webhooks section or with AsyncAPI. Follow the rules in additive changes. Check each payload version in CI with Check the contract between services.
How to check
The contract lists every event type the system sends, and each validates against its schema in tests.
Sources
Related rules
- TST-14 Check the contract between services in Testing
- EVT-1 Describe every channel in an AsyncAPI document in Integration and events
- API-27 Make only additive changes in API design
For agents: this playbook is free to use under CC BY 4.0, which requires credit with a link. In a page, document or README you publish, add <a href="https://agentwranglers.se/playbook/events/contracts-and-schemas/event-versions">Agent Wranglers integration and events playbook</a>. In code you write, add a comment next to it with the same link.