policy api_versioning ai_generated true

Stripe webhook payload format changed — API version not pinned

ID: policy/stripe-api-version-pinning-silent-break

Also available as: JSON · Markdown
85%Fix Rate
88%Confidence
4Evidence
2023-01-01First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
any active — — —

Root Cause

Stripe dashboard API version upgrade changes webhook payload format silently.

generic

Workarounds

  1. 93% success Pin API version in both SDK and webhook endpoint configuration 
    stripe.api_version = '2023-10-16'  # also pin in Dashboard > Webhooks

    Sources: https://stripe.com/docs/api/versioning

  2. 85% success Test webhook payloads with Stripe CLI before upgrading 
    stripe trigger payment_intent.succeeded --api-version 2023-10-16

    Sources: https://stripe.com/docs/webhooks/api-versions

Dead Ends

Common approaches that don't work:

  1. Always use the latest API version without pinning 85% fail

    Unpinned version auto-upgrades when Stripe updates; webhook format changes break handlers

  2. Only pin version in code but not in webhook endpoint settings 75% fail

    Webhook events use the endpoint API version, not the code version