Skip to Content
WebhooksWebhook Versioning

Webhook Versioning

Asiri webhook events use a versioned envelope so subscribers can migrate safely when an event payload changes.

Every delivery uses this top-level shape:

{
  "event_version": 1,
  "event_type": "dsr.created",
  "event_id": "evt_01HXYZ",
  "occurred_at": "2026-05-15T12:00:00.000Z",
  "tenant_id": "00000000-0000-4000-8000-000000000001",
  "data": {}
}

Rules

  • event_version is an integer and is versioned per event_type.
  • Backward-compatible optional fields may be added without bumping the version.
  • Breaking changes bump the affected event type to the next integer version.
  • Subscriptions receive the platform default version unless they set pinnedVersions.
  • pinnedVersions is a map of event_type to version, for example { "dsr.created": 1 }.
  • Pins must reference event types included in the subscription’s events list.
  • Delivery requests include X-Asiri-Event-Version.
  • Deprecated versions include X-Asiri-Webhook-Deprecated: YYYY-MM-DD.

Subscriber Guidance

  • Branch on (event_type, event_version) before parsing data.
  • Ignore unknown fields in the envelope and data.
  • Respond with any 2xx status to acknowledge receipt.
  • Pin only versions you have tested locally.

Breaking-Change Lifecycle

  1. A new version ships alongside the previous version.
  2. Deprecated versions remain available for six months after the new version ships.
  3. Admin users see warnings for subscriptions pinned to deprecated versions.
  4. After the retirement date, removed versions are no longer accepted for new pins.

TypeScript Shape

type AsiriWebhookEnvelope<TType extends string, TData> = {
  event_version: number;
  event_type: TType;
  event_id: string;
  occurred_at: string;
  tenant_id: string;
  data: TData;
};
Webhooks Overview