Webhook API Versioning

Intro

Khaime uses date-based versioning for webhook payloads, pinned per API key, so a change to the payload shape never breaks an integration that isn’t ready for it. The current version is 2026-03-28.

Context

The version travels with every delivery — in the envelope’s api_version field and in the X-Khaime-Api-Version header (see Webhooks Overview) — so your handler can always tell which schema shape it’s looking at, even if you’re running multiple integrations against keys created at different times. This page explains what counts as a breaking change and walks through the last major payload migration; for the event types and fields themselves, see Events.

Hows

How versions work

api_version is a date string (e.g., "2026-03-28") stored on each API key record.
The version is included in the webhook body (api_version field) and the X-Khaime-Api-Version response header.
New API keys are assigned the current version (2026-03-28) at creation time.
Existing keys keep the version they were created with — every subsequent delivery on that key uses the same payload shape, indefinitely.

There is currently no self-serve endpoint to change the api_version on an existing key. If you need a key upgraded to the latest schema, create a new API key (sandbox or live) — new keys always start on the current version.

What triggers a new version

Change type	New version required?
New optional field added to an existing object	No
New event type added	No
Field renamed or removed	Yes
Field type changed (e.g., number to string)	Yes
Nested object restructured	Yes

Adding new optional fields or new event types is non-breaking — your integration should handle unknown fields gracefully.

Migration guide: legacy payloads to 2026-03-28

The 2026-03-28 version is the first date-versioned webhook schema. It introduced structured multi-currency amounts, an explicit envelope (api_version, event_id, business_id), and expanded event coverage beyond the original flat payment/subscription events. If you’re integrating fresh today, every new API key already uses this version — this section exists for reference if you’re working from an older integration built against the pre-versioning payload shape.

Key changes

Area	Before	After (`2026-03-28`)
Amounts	Flat `amount` and `currency` fields	Structured `MulticurrencyBreakdown` with `customer_paid`, `merchant_gross`, `merchant_net`, and `fees`
Customer	Nested under `data.customer` with `paid_amount` / `paid_currency`	Clean `customer` object; payment amounts moved to `amounts`
Product info	Flat `product_id` in data, details in `transaction_details`	Structured `product` object with `id`, `title`, `type`
Transaction details	`transaction_details` sub-object	Fields promoted to top level (`payment_type`, `gateway`)
Envelope	No `api_version` or `business_id`	Both always present

Event mapping

Previous event	New event	Payload changes
`payment.succeeded`	`payment.succeeded`	Amounts moved into `MulticurrencyBreakdown`; `product`, `installment` fields added
`payment.failed`	`payment.failed`	Same restructuring
`subscription.created`	`subscription.created`	`plan`, `current_period`, `trial` fields added
`refund.completed`	`payment.refunded`	Now part of the `payment.*` group with a `refund` sub-object
(new)	`wallet.credited` / `wallet.debited`	Wallet operations now fire events
(new)	`settlement.*`	Full payout lifecycle tracking
(new)	`dispute.*`	Dispute lifecycle events
(new)	`account.updated`	Merchant payment account / KYC status tracking
(new)	`order.*`	Physical product fulfillment tracking

Example: payment.succeeded

{
  "event_type": "payment.succeeded",
  "event_id": "evt_123456_1708900000000",
  "occurred_at": "2026-01-16T21:05:00.000Z",
  "is_live": true,
  "data": {
    "transaction_id": "456",
    "amount": 5000,
    "currency": "USD",
    "status": "success",
    "customer": {
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe",
      "paid_amount": 5000,
      "paid_currency": "USD"
    },
    "transaction_details": {
      "payment_type": "one_time",
      "product_type": "digital",
      "product_title": "Premium Plan",
      "payment_gateway": "stripe",
      "created_at": "2026-01-16T21:00:00.000Z"
    }
  }
}

{
  "api_version": "2026-03-28",
  "event_id": "evt_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "event_type": "payment.succeeded",
  "occurred_at": "2026-01-16T21:05:00.000Z",
  "is_live": true,
  "business_id": "1042",
  "data": {
    "object": "payment",
    "id": "456",
    "status": "succeeded",
    "payment_type": "one_time",
    "gateway": "stripe",
    "gateway_reference": "ch_abc123",
    "amounts": {
      "customer_paid": { "amount": 5000, "currency": "USD" },
      "merchant_gross": { "amount": 5000, "currency": "USD" },
      "merchant_net": { "amount": 4400, "currency": "USD" },
      "fees": {
        "platform_fee": { "amount": 300, "currency": "USD" },
        "gateway_fee": { "amount": 300, "currency": "USD" },
        "total": { "amount": 600, "currency": "USD" }
      }
    },
    "product": {
      "id": "3046",
      "title": "Premium Plan",
      "type": "digital"
    },
    "customer": {
      "email": "jane@example.com",
      "first_name": "Jane",
      "last_name": "Doe"
    },
    "created_at": "2026-01-16T21:00:00.000Z",
    "paid_at": "2026-01-16T21:05:00.000Z"
  }
}

Whys

Versioning is per-key and date-based, rather than a global cutover, so a payload restructuring never breaks an integration mid-flight — a key minted a year ago keeps receiving the shape it was built against until you deliberately move to a new key. Dates (rather than v1/v2) were chosen so the version string itself tells you when the schema was frozen, without needing to cross-reference a separate changelog to know what it contains. The bar for a “new version” is deliberately narrow — additive changes (new optional fields, new event types) never require one — because if every addition forced a version bump, partners would be stuck perpetually behind the latest event coverage just to avoid unrelated breaking changes elsewhere in the schema.

Why nots

This isn’t a live API changelog — it documents the versioning model and the one payload migration that has happened so far, not a running log of every field ever added. Check Events for the current, authoritative payload shape regardless of which version you’re on; additive fields and new event types show up there without a corresponding entry here. Versioning also doesn’t cover delivery mechanics (timeouts, retries, signing) — a version change never affects headers, the signing algorithm, or the retry policy. Those are stable across every api_version and documented in Webhooks Overview and Signature Verification.

Getting Started

Payments

Webhooks

API Versioning

Webhook API Versioning

Intro

Context

Hows

How versions work

What triggers a new version

Migration guide: legacy payloads to 2026-03-28

Key changes

Event mapping

Example: payment.succeeded

Whys

Why nots

​Webhook API Versioning

​Intro

​Context

​Hows

​How versions work

​What triggers a new version

​Migration guide: legacy payloads to 2026-03-28

​Key changes

​Event mapping

​Example: payment.succeeded

​Whys

​Why nots

Webhook API Versioning

Intro

Context

Hows

How versions work

What triggers a new version

Migration guide: legacy payloads to 2026-03-28

Key changes

Event mapping

Example: payment.succeeded

Whys

Why nots