Yes. Pin the API version in your requests and in each webhook endpoint, upgrade it on your own schedule after testing in a sandbox, and treat SDK upgrades as possible version changes. An unpinned integration can change behavior without a single line of your code changing.
What changes when a version changes
API versions can alter response fields, defaults, error shapes and the structure of webhook payloads. A handler written for one shape can fail or, worse, misread another. If a payment status field changes meaning, your fulfilment logic might ship goods for unpaid orders. That is a security and integrity issue as well as a bug.
How one provider handles versions
The go-live checklist from one payment provider is useful here:
- All requests use your account API settings unless you override the version.
- Webhook events are structured according to your account API version by default, unless you set a version when you create the endpoint.
- In strongly typed languages such as Go, Java, TypeScript and .NET, the server library pins the version based on the library release you use.
- In dynamic languages such as Node.js, PHP, Python and Ruby, you set the version in the library yourself.
- Upgrading is done by moving the account to the latest version in the dashboard, or by upgrading the library.
Two lessons follow. The version can live in three places: the account, the request, and the webhook endpoint. And a routine library upgrade can silently change the version in typed languages.
A pinning policy you can adopt
- Record the version. Write it in the repository next to the integration code.
- Set it explicitly in client construction, not through an account default.
- Set it on webhook endpoints at creation, so event payloads match your handler.
- Treat vendor SDK bumps as API changes. Read release notes and rerun integration tests.
- Upgrade in a sandbox first. Replay recorded events through the new version and compare handler output.
- Plan upgrades twice a year, or on a calendar your team sets, so the gap never grows large.
- Subscribe to the vendor's API update announcements. The go-live checklist recommends this.
Version drift table
| Place | Risk if left to default | Pinning action |
|---|---|---|
| Account setting | Someone upgrades in the dashboard and breaks code | Restrict who can change it, and log changes |
| Request header or client config | Behavior differs between services | Set it in shared client code |
| Webhook endpoint | Payload shape changes under the handler | Set at creation, test before changing |
| SDK version | Upgrade moves the pinned version | Review release notes in the pull request |
Do not pin forever
Old versions miss fixes and features, and vendors eventually retire them. Pinning is about control over timing, not avoiding upgrades. The provider-side view is in your old API version did not get the fix.
Try it yourself
Click through it at your own pace, or open it full screen. See how each SDK and its version shows up in one inventory.
Where Safeguard fits
Safeguard's dependency scanning and SBOM show which vendor SDK versions you run, and policy gates can require review when they change. Try the free scan.
Quick check
Can an SDK upgrade change my API version?
In strongly typed languages, the provider cited below says the library pins the version based on the release you use, so yes. Review release notes.
Does the webhook payload follow my request version?
By default it follows the account version unless you set one when creating the endpoint, so set it explicitly.
Sources
- Go-live checklist, Stripe documentation
Last reviewed: 19 October 2026.
