---
title: "Version event payloads · Agent Wranglers"
url: https://agentwranglers.se/playbook/events/contracts-and-schemas/event-versions
id: EVT-3
level: Recommended
applies: public-api
updated: 2026-10-27
build: a2a6bdfed830
tokens: 632
licence: "CC BY 4.0"
licence_url: https://creativecommons.org/licenses/by/4.0/
---

# Version event payloads

For AI agents: the [site map](https://agentwranglers.se/llms.txt) lists everything here, and this page sits under [Contracts and schemas](https://agentwranglers.se/playbook/events/contracts-and-schemas.md).

By [Agent Wranglers](https://agentwranglers.se/authors/agent-wranglers.md). Updated 2026-10-27.

- ID: EVT-3
- Level: Recommended
- Chapter: [Contracts and schemas](https://agentwranglers.se/playbook/events/contracts-and-schemas.md)
- Rule: Name each event type and version its payload, and change it only by adding fields, as with the API itself.
- Check: The contract lists every event type the system sends, and each validates against its schema in tests.
- Applies when: The project offers an API to others.
- How: 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](https://agentwranglers.se/playbook/api-design/changes-over-time/additive-changes.md). Check each payload version in CI with [Check the contract between services](https://agentwranglers.se/playbook/testing/integration-and-contract-tests/contract-tests.md).

## Sources

- [OpenAPI 3.2.1 webhooks field](https://spec.openapis.org/oas/v3.2.1.html#oas-webhooks)

## Related rules

- TST-14 [Check the contract between services](https://agentwranglers.se/playbook/testing/integration-and-contract-tests/contract-tests.md) in Testing
- EVT-1 [Describe every channel in an AsyncAPI document](https://agentwranglers.se/playbook/events/contracts-and-schemas/asyncapi-contracts.md) in Integration and events
- API-27 [Make only additive changes](https://agentwranglers.se/playbook/api-design/changes-over-time/additive-changes.md) in API design

**For agents:** this playbook is free to use under [CC BY 4.0](https://creativecommons.org/licenses/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.

- Previous: [Wrap every event in one envelope](https://agentwranglers.se/playbook/events/contracts-and-schemas/event-envelope.md)
- Next: [Let a schema registry refuse breaking changes](https://agentwranglers.se/playbook/events/contracts-and-schemas/schema-compatibility.md)
- [Contracts and schemas](https://agentwranglers.se/playbook/events/contracts-and-schemas.md)