Help for owners
After a Stripe upgrade my checkout or webhooks stopped working
Short answer
Stripe returns data in the shape of an API version, and your code, your Stripe library and your webhook endpoints can each use a different one. A change to any of them can break checkout or order updates. Find which version each part uses before changing anything, and upgrade webhooks with a new endpoint.
Does this sound like your situation?
- Payments stopped completing, or orders are not marked paid, right after someone upgraded.
- Stripe's dashboard shows payments succeeding but my site does not react.
- Errors mention a missing field, an unknown parameter or a changed value.
- Everything worked in testing but fails for real customers.
- The developer updated the Stripe library and now parts of checkout fail.
Why does this happen?
Your account has a default version
If a request does not name a version, Stripe uses the account's default API version, which defines how the API is called and the shape of responses. Stripe recommends specifying the version in code so your code decides, not the Dashboard setting.
Confirmed by docs.stripe.com
Major releases can break your code
Stripe releases new versions monthly with no breaking changes, and issues a major release twice a year that starts with an API version containing breaking changes. Upgrading to a major release can require code changes.
Confirmed by docs.stripe.com
A library upgrade can change the version too
Recent releases of the server libraries use the API version that was current when the library was released. In strongly typed languages such as Java, Go and .NET the version is fixed to the library, so upgrading the library changes what you get.
Confirmed by docs.stripe.com
Webhooks have their own version
A webhook endpoint uses the version set when it was created, otherwise the account default. Stripe notes that the endpoint version is independent of the version used by your server library, so events can arrive in a shape your handler does not expect.
Confirmed by docs.stripe.com
Webhook verification is part of the change
Stripe says upgrading webhook endpoints means verifying incoming signatures and allowing traffic from Stripe's public IP addresses. A change of endpoint or secret can make every event fail verification.
Confirmed by docs.stripe.com
What can I do about it today?
- Do not click upgrade or roll back at randomRandom changes in the Dashboard can leave code and webhooks on different versions. First find out who changed what and when.
- Ask what changed, in writingAsk your developer or agency for the date, the library version before and after, and whether the Dashboard default version was changed.
- Look at the webhook delivery logIn Stripe's Dashboard, open your webhook endpoint and check whether recent events were delivered and what response your site returned.
- Check whether customers were chargedCompare the payments in Stripe with your orders. List the ones that were paid but not recorded and keep the list safe. Do not re-charge customers.
- Pause new releasesUntil the cause is known, ask for no further upgrades or deploys on the payment parts.
- Ask for a test runStripe documents testing in a sandbox, so any fix should be proved there first.
When should I bring someone in?
- Paid orders are not being recorded and customers are asking where their purchase is.
- Nobody can say which version the code and the webhooks use.
- The person who did the upgrade is not reachable.
How do I handle it?
- Inventory every versionI list the version used by the account default, each library call and each webhook endpoint, using the Stripe Dashboard's tools and your code.
- Read the changelog for your callsI check Stripe's changelog for the changes that affect the requests and events your integration really uses.
- Fix forward in a sandboxI reproduce the failure in a Stripe sandbox, fix the handler and run test payments through the changed paths.
- Migrate webhooks the documented wayI follow Stripe's steps of a new endpoint, handling both for a time, and disabling the old one after monitoring, so no event is lost.
- Recover missed ordersI reconcile payments against orders and repair the ones that did not record, with a record of each change.
The price depends on what I find, so I quote in writing after a short discovery call. Tell me what is happening and I reply within 24 hours.
What do owners ask about this?
Can I just go back to the old version?
It depends on which part changed. The Dashboard version, your library and each webhook endpoint are separate settings, so reverting one may not repair the others.
Are monthly Stripe versions safe?
Stripe says it can be safe to upgrade to any monthly release without code changes. A major release can require them.
Why do payments succeed but my orders do not update?
Often the webhook handler is rejecting or misreading the events. The delivery log shows the response your site sent.
Where is the full list of changes?
Stripe publishes a developer changelog of every API change.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Found a mistake? Tell me.