Handle webhook versioning
Learn how to upgrade the API version of your webhook endpoint.
Webhook endpoints either have a specific API version set, or use the default API version of the Stripe account. To upgrade to a newer API version with no downtime, follow the steps below in test mode and then in live mode.
Create a new disabled webhook endpoint
Create a new webhook endpoint with the following parameters:
url
: the same URL as your original webhook endpoint, but add a query parameter to distinguish between events sent to the two different endpoints. For examplehttps://example.
.com/webhooks?version=2024-04-10 enabled_
: the same events as your original webhook endpoint.events api_
: the API version you want to upgrade to. If you’re upgrading to the latest API version, you can use the Dashboard or the API to create the endpoint. For other versions, use the API to set a specific version.version
After you create the new webhook endpoint, disable it. You will re-enable it in the next step.
Update your webhook code to ignore events sent to the new endpoint
Update your event processing code:
- If the query parameter is for the older API version, process it as usual.
- If the query parameter is for the newer API version, ignore the event and return a 200 response to prevent delivery retries.
Next, enable the new webhook endpoint that you created in the previous step. At this point every event is sent twice: once with the old API version and once with the new one.
Update your webhook code to process events for the new endpoint
Update the version of the Stripe library you’re using to match the version of your new webhook endpoint. Make sure to read the changelog and handle any breaking changes.
Update your event processing code:
- If the query parameter is for the older version, ignore the event. We recommend returning a 400 status to let Stripe automatically retry the event. This ensures that if you need to revert, events are re-sent to the older webhook endpoint.
- If the query parameter is for the new version, process it.
Monitor your new webhook endpoint
If events aren’t being correctly handled by your new code, try the following:
- Revert to the earlier version of your code.
- Temporarily disable the new webhook endpoint.
- Process the failed events (if you returned a 400 status as described in the previous step, Stripe automatically resends all the events).
- Investigate and fix the issue.
- Enable the new webhook endpoint and resume monitoring.
Disable the old webhook endpoint
If the upgrade is successful, you can disable the old webhook endpoint. Delivery of events where you returned a 400 status won’t be retried after the webhook endpoint is disabled.