Event Schema Versioning Policy

Last updated: 2026-02-18

This policy governs webhook event payload compatibility for enterprise consumers.

Versioning model

• Payload version field: apiVersion
• Current value source of truth: src/lib/webhooks/events.ts (WEBHOOK_PAYLOAD_VERSION)
• Format: date-based (YYYY-MM-DD)

Compatibility guarantees

1. Additive changes (new top-level optional fields) can be introduced without changing major integration behavior.
2. Existing required fields are not removed inside the same apiVersion.
3. Event type names are stable and treated as contract identifiers.
4. Breaking payload changes require a new apiVersion and coordinated rollout notice.

Where version appears

• Webhook payload body (apiVersion)
• AsyncAPI contract header fields (x-webhook-version)
• AsyncAPI payload schema constants

Consumer guidance

1. Validate x-webhook-version and payload apiVersion together.
2. Ignore unknown additive fields.
3. Treat missing required fields as non-retryable schema errors.
4. Pin contract snapshots from:
   • docs/integration-opportunities/contracts/asyncapi.webhooks.v1.json
   • docs/integration-opportunities/contracts/openapi.enterprise.v1.json

Reference implementation:

• sdks/typescript/src/webhooks.ts
• validateWebhookEnvelopeConsistency
• parseWebhookPayload
• WebhookSchemaValidationError (retryable = false)

Change management

1. Update WEBHOOK_PAYLOAD_VERSION.
2. Regenerate contracts (npm run contracts:export).
3. Publish SDK/contract release notes.
4. Keep old payload versions in replay logs for forensic traceability.