The Tool Desk
Outbyte Driver Updater FREEScan for outdated or missing drivers - takes under a minuteDriver Scan →Outbyte PC Repair FREEClear out junk files and repair common Windows errorsFree Scan →When a Stripe webhook handler suddenly stops working, the cause is usually one of three things: an API version that changed for your endpoint or SDK, a documented breaking release, or parsing code that assumed a field would always be present. Stripe publishes breaking changes, so the word “silently” is hard to prove from the outside. This guide shows how to tell which situation you are in, walks through a documented example of a breaking field move, and describes a schema-drift check that flags payload changes before they turn into failed orders.
What the original report describes
A first-person article by Kuba on DEV Community, dated March 23, 2026, describes a client whose orders stopped going through after a field changed in a payment_intent.succeeded webhook payload. The author proposes flattening payloads, comparing schemas separately for each endpoint and event type, and alerting when a schema changes.
As an Amazon Associate I earn from qualifying purchases.
Those are the author’s account and design proposal. The specific field change, the lack of notice, the debugging time, and the reported results have not been independently verified, and they are not a Stripe-confirmed incident. The useful part is the detection pattern, which you can apply to your own integration whatever caused the change.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Separate the two API versions before you debug
Two different version settings affect what your application receives, and they are easy to conflate:
#1 Best Overall
| Setting | What it controls | Where to check it |
|---|---|---|
API version for outgoing requests (set by a Stripe-Version header, an SDK pin, or the account default) |
The response shape for API calls your code makes, such as retrieving a PaymentIntent | Your request code, your SDK’s documentation and lock file, and the account’s API version settings in the Dashboard |
| Webhook endpoint API version | The shape of event payloads delivered to that endpoint | Developers > Webhooks in the Dashboard, on the endpoint’s detail page |
| Account default version | The fallback used when an endpoint does not specify its own version | The account’s API version settings in the Dashboard |
Stripe’s webhook documentation says events use the version configured on the endpoint, or the account default if the endpoint has none. Most v1 events contain a versioned snapshot of the resource as it was when the event occurred. Two endpoints on the same account can therefore receive differently shaped events for the same event type.
How Stripe versions its API
Stripe’s API versioning documentation describes two kinds of release. Major releases can include backward-incompatible changes that require code changes. Monthly releases are described as backward-compatible. Stripe recommends testing a new API version before you upgrade to it.
Stripe’s versioning documentation has listed 2025-06-30.basil as the current version. Versions change, so check the live value in the Dashboard before relying on it.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Outdated Drivers Are Slowing You Down
One free scan finds every outdated or missing driver and matches the right update for your exact hardware.Free scan · exact hardware matchRank #2
- HTML CSS Design and Build Web Sites
- Comes with secure packaging
- It can be a gift option
Stripe guarantees access to events through the Retrieve Event API for 30 days. After that window, keep your own copy of webhook payloads if you need them for debugging, audits, or replay.
A documented example: subscription period fields moved
The clearest recent example of a breaking change in Stripe’s own documentation is the 2025-03-31.basil release. The changelog entry states that current_period_start and current_period_end were removed from the Subscription object and added to SubscriptionItem. Code that read those fields from the subscription itself needed to read them from the subscription item instead.
In practice, a handler that did this:
period_end = subscription["current_period_end"]needs to read from the first item in the subscription’s items list:
Rank #3
period_end = subscription["items"]["data"][0]["current_period_end"]The changelog gives an upgrade sequence for this change: check the current version in the Workbench, align your SDK or request header, upgrade webhook endpoint API versions, test the integration (including Connect if you use it), and then perform the Workbench upgrade. The changelog describes a 72-hour rollback for that upgrade flow. Confirm the rollback window and controls in the current Dashboard before you plan around them, because the process may have changed since that entry was written.
Diagnosing a handler that stopped working
Work through these steps in order. Each one rules out a common cause before you consider a provider-side change.
- Record the failing event ID, event type, delivery timestamp, and the webhook endpoint ID that received it.
- Open the endpoint’s detail page under Developers > Webhooks and note its API version. Check the endpoint’s edit history if your team has one, because an endpoint version change is a common cause of a payload shape change.
- Compare the account’s default API version with the endpoint’s version.
- Check your SDK version and lock file against your last deploy. An SDK upgrade can change how request and response objects are constructed.
- Retrieve the event with the Retrieve Event API while it is still within 30 days, or use your stored copy of the payload.
- Compare the failing payload with a known-good payload of the same event type and the same endpoint version. Look for added fields, removed fields, type changes, and fields that switch between null and absent.
- Read the changelog for every version between the one your endpoint uses and the current one, looking for removals, moves, and migration instructions.
- Review your own deploy history and parsing code, especially any assumption that an optional field is always present.
A handler failure does not on its own establish that Stripe changed a schema. Application deploys, endpoint version changes, differences between event types, optional fields that appear only for some records, and parsing assumptions can all produce the same symptom.
Rank #4
- Brand: Wiley
- Set of 2 Volumes
- A handy two-book set that uniquely combines related technologies Highly visual format and accessible language makes these books highly effective learning tools Perfect for beginning web designers and front-end developers
Building a schema-drift check
The check the original author proposes is an application-level safeguard. It does not change how Stripe sends events. Its job is to notice when the shape of incoming payloads differs from what you have seen before. The design below follows that pattern and adds a few safeguards.
1. Flatten each payload into typed paths
Convert nested JSON into dotted paths with a type for each leaf value, so that differences are easy to compare:
Quick wins for a faster PC:
Clear out junk files and repair common Windows errorsFree Scan →Scan for outdated or missing drivers - takes under a minuteDriver Scan →def flatten(obj, prefix=""):
out = {}
if isinstance(obj, dict):
for k, v in obj.items():
path = f"{prefix}.{k}" if prefix else k
out.update(flatten(v, path))
elif isinstance(obj, list):
for v in obj:
out.update(flatten(v, f"{prefix}[]"))
if not obj:
out[prefix] = "list"
else:
out[prefix] = "null" if obj is None else type(obj).__name__
return outRecord whether each path was present, null, or absent. A field that switches between null and absent is a different signal from one that is always present.
2. Keep baselines separate by endpoint, API version, and event type
Store one baseline for each combination of webhook endpoint, endpoint API version, and event type. Comparing a payment_intent.succeeded payload with a customer.subscription.updated payload produces false alarms, and comparing payloads from two different endpoint versions produces the same problem. Keying the baseline by version also lets you tell a planned migration from unexpected variation.
3. Classify differences by risk
- Removed field that your code reads: highest priority. Review immediately.
- Type change on a field your code reads: high priority.
- Added field: usually low priority, but review it if it is in a payload your team relies on.
- Null/absent switch on an optional field: review, and check whether your code handles both states.
Treat every classification as a prompt for review. A diff is evidence of a change in what arrived, not proof of its cause.
4. Test in two places
- Continuous integration: keep captured payloads for each event type and endpoint version as fixtures, and fail the build when your parser cannot read them. This catches your own assumptions before a deploy.
- Live traffic: sample incoming payloads, compare them with the baseline, and log or alert on differences.
5. Do not let the checker block event processing
Persist the raw event and process it first. Run the drift comparison afterwards, and make sure a failure in the checker does not change the response your endpoint returns to Stripe unless your team has chosen that failure mode deliberately. A monitoring bug should not stop payment processing.
Troubleshooting branches
- The failing payload matches its baseline, but the handler still fails: the problem is probably in your code or in data-dependent values. Reproduce it with the exact payload.
- The shape changed after an endpoint version change: review the migration steps for that version and update the parser for that endpoint.
- The shape changed after an SDK upgrade with no endpoint change: check the SDK’s release notes and align the SDK with the API version you are targeting.
- The shape changed with no version change and no deploy: keep the captured event IDs and payloads, check the changelog, and contact Stripe support with those details before you conclude anything about the cause.
What a drift alert can and cannot show
A drift alert shows that the payloads your endpoint receives for a given event type and version no longer match the shape you recorded. It can catch a provider-side change, but it can also catch a misconfigured endpoint, a mixed SDK fleet, or a deploy that changed how your code builds requests. The alert starts an investigation. The diagnosis steps above are what determine the cause.
The fix the original author describes is worth building, but its value depends on baselines that match real traffic, on alerts that are reviewed, and on processing that continues when the checker fails.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
