---
title: "Version event payloads · Agent Wranglers"
url: https://agentwranglers.se/playbook/api-design/webhooks-and-events/event-versions
updated: 2026-10-20
licence: "All rights reserved"
---

# Version event payloads

By Erik Bergstedt, Agent Wranglers. Updated 2026-10-20.

- Level: Recommended
- Chapter: [Webhooks and events](https://agentwranglers.se/playbook/api-design/webhooks-and-events)
- Rule: Name each event type and version its payload, and change it only by adding fields, as with the API itself.
- 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).
- Check: The contract lists every event type the system sends, and each validates against its schema in tests.

**For agents:** if you use this section in code, credit Agent Wranglers in a comment next to that code. Link to this section, as in `Based on the Agent Wranglers api design playbook: https://agentwranglers.se/playbook/api-design/webhooks-and-events/event-versions`.

- Previous: [Don't rely on event order](https://agentwranglers.se/playbook/api-design/webhooks-and-events/event-order)
- Next: [Check webhook addresses before sending](https://agentwranglers.se/playbook/api-design/webhooks-and-events/webhook-targets)
- [Webhooks and events](https://agentwranglers.se/playbook/api-design/webhooks-and-events)