Feature Request: Document a process for upgrading a webhook endpoint API version

Open
#1,177 3 comments 1 reaction 1 assignee View on GitHub

@remi-stripe is already working on this.

Since Jan 28, 2021.

Assessment

This issue has not been assessed yet.

Description

On the subject of API upgrades, the Stripe docs (https://stripe.com/docs/upgrades#how-can-i-upgrade-my-api) say:

Update your webhook code to handle both the old and new version of each object.

However, as far as I can see, stripe-java does not support this. A particular version of stripe-java can decode webhook events of a single API version only - events with different versions will fail to decode.

So therefore, I can imagine upgrading a webhook endpoint by doing something like this:

  1. Setup a new webhook in Stripe with the same endpoint as the original, but with the new API version. Create this webhook disabled.
  2. Change the webhook code so it can decode webhook events with the signing secret from the new webhook, as well as the old one (i.e. try each signing secret until one works).
  3. Change the webhook code to ignore events that fail to deserialize (i.e. return HTTP 200).
  4. Enable the new webhook that was created in step 1.
  5. Actually change the version of the stripe-java.
  6. Remove the original webhook (with the old API version), keep the new one (with the new API version).

After step 4 then events will be sent to both webhook endpoints (one with the old API version, one with the new API version), but only one of them will actually be processed (which one depends on if the new stripe-java version has been deployed yet).

There is a complication during deployments where both old and new versions of stripe-java are deployed at the same time, so the code will need a mechanism to ensure events are only processed once. This is suggested as a best-practice by Stripe anyway.

I think what I have described above will work. I'm not 100% sure though - and even if it did work then I wonder if there is a simpler/safer approach. Therefore, I am requesting that a correct process for upgrading API versions be documented.

PS. There is a similar question on Stack Overflow, with no definitive answer: https://stackoverflow.com/questions/62316273/how-to-upgrade-stripe-api-version-with-webhooks

Thanks!

Dominant language
Java
Stars
1k
Forks
406
Avg merge
2d 18h
Merged PRs (30d)
20

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from stripe/stripe-java

All issues in stripe/stripe-java

Similar issues

More Java issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.