Contract versioning

Qanivo public integration contracts use explicit major versions. A compatible 1.x change may add optional fields or informational event types when existing consumers can safely ignore them. A breaking field, route, signing, or status change requires a new major version and a migration guide.

The version applies to the selected surface, not to every provider or product API. Provider Webhook versions remain provider-specific; Event Hook, Workflow, and Lead Delivery envelopes use their Qanivo contract/version policy.

Consumer rules

• Pin the major version and record it with each idempotent delivery record.
• Reject unsupported major versions and unknown security-sensitive commands.
• Ignore only additive informational fields allowed by the contract.
• Keep the exact raw body for the short verification window only when policy permits, then retain redacted evidence.
• Test surface-specific signature framing, timestamp/replay windows, idempotency, retry classification, and terminal disablement for each version.

export function acceptVersion(contractVersion: string) {
  if (!/^1\.\d+$/.test(contractVersion)) throw new Error('unsupported webhook contract version');
  return true;
}

acceptVersion('<YOUR_CONTRACT_VERSION>');

See HTTP and errors, Signing and verification, and Security, observability, and versioning for the operational contract.