Stripe API version mismatch: events your SDK does not understand

TL;DR: API responses include fields your SDK types do not have, or lack fields the latest docs describe. # Stripe API version mismatch: events your SDK does not understand ## The symptom Webhook handlers break on events with unfamiliar shapes. Upgrading the SDK changes behavior in production. ## Confirm the cause Two version axes must agree: 1.

Stripe API version mismatch: events your SDK does not understand

The symptom

Webhook handlers break on events with unfamiliar shapes. API responses include fields your SDK types do not have, or lack fields the latest docs describe. Upgrading the SDK changes behavior in production.

Confirm the cause

Two version axes must agree:

1. Your SDK's default version. Each SDK release targets a specific Stripe API version. Check stripe.VERSION or your lockfile.
2. Your webhook endpoint's version. Each endpoint in the dashboard has its own API version setting, independent of your SDK. An endpoint created a year ago delivers year-old event shapes even if your SDK is current.

Stripe also sends api_version on every event object. Log it and compare with what your code expects.

The fix

• Pin deliberately: set the API version explicitly when constructing the client (apiVersion: '2024-...'), and set each webhook endpoint's version in the dashboard to match. Mismatched pairs are the bug.
• Upgrade on a schedule: read the API changelog for breaking changes, upgrade the SDK in a branch, run your webhook fixtures against the new event shapes, then bump the endpoint version.
• Keep version-gated code paths short: if (event.api_version < EXPECTED) should log and alert, not silently parse. An unknown shape parsed optimistically is how money bugs happen.
• Test webhooks use the endpoint's version, so "send test webhook" exercises the real shape. Use it after every bump.

Verify the fix

Log event.api_version for a week and confirm it matches your pinned version on every endpoint. After an SDK upgrade, replay your stored event fixtures and confirm all handlers pass. Confirm no endpoint in the dashboard sits on a version older than your code expects.

When to use

You hit exactly this: Stripe API version mismatch: events your SDK does not understand in Stripe API version mismatch.

When not to use

A different error, or the same symptom in a different tool. This page only covers the failure above.

Compatibility

Stripe API version mismatch.

Edge cases

• should log and alert, not silently parse.
• for a week and confirm it matches your pinned version on every endpoint.

Stripe's API versioning documentation explains that each webhook endpoint has its own API version setting and that SDK releases target specific API versions, and that events carry their api_version (docs.stripe.com/api/versioning). Mismatches between endpoint version and SDK expectations are the documented cause of unfamiliar event shapes.