Plugins using webhooks should update their onboarding and documentation

[mg-stripe]

What does Stripe consider to be a plugin?

Stripe defines a plugin as any integration between a third-party solution and Stripe that requires a user to authenticate with their secret API keys. A plugin typically interacts with Stripe APIs either by making API calls or reacting to Stripe API events on behalf of its users. Often plugins run code so Stripe can interact with other software (e.g. accept payments on Wordpress), but they may take other shapes too, like any website or open-source library.

What are the changes Stripe is introducing?

Stripe will release three new developer tools which will impact how your users set up webhook endpoints: Workbench, Event Destinations, and Sandboxes. You should implement the guidance in this thread in August so that your users can successfully set up your Stripe plugin. If you don’t make these changes, your users’ onboarding flow may be disrupted.

What’s changing:

• Workbench will replace the Developer Dashboard as the new home for completing developer tasks, including setting up webhook endpoints. By September, all new Stripe accounts will start using Workbench by default. Existing users will continue to use the Developers view in the Dashboard until they choose to opt in.
• Event Destinations evolve our webhook event offering to provide more flexible ways to consume Stripe events. Event Destinations will support webhook endpoints, Amazon EventBridge, and other cloud destinations in the future. On 8/19, users will be able to opt in to use Event Destinations.
• Sandboxes will offer new testing environments in addition to test mode, allowing users to set up multiple, isolated testing environments in their Stripe account. On 8/19, all Stripe accounts will have access to Sandboxes.

For your plugin, these changes will not cause any impact to currently-running integrations for your users—they primarily impact the steps needed for a user to configure a webhook endpoint from the Stripe Dashboard.

How do I get access to the new developer tools?

To get access to Workbench, configure the setting for your user login from the Beta features in the Dashboard. Fill out this form for access to Event Destinations and this form to request access to Sandboxes.

Do I need to update my plugin for these changes?

If your plugin requires your user to configure a webhook endpoint (e.g. to complete a payment flow, or to synchronize data from Stripe), you will need to update your onboarding flow and documentation to use Workbench. You can choose to either:

1. [Immediate fix] Update your onboarding flow and documentation to use template links and Workbench: if you require your users to configure a webhook endpoint (and the event types for that endpoint), follow the steps below so your plugin’s users can manually set up webhooks to ensure a smooth transition.
2. [Recommended] Migrate to a Stripe App using the OAuth 2.0 authentication method: using the Stripe Apps framework, you can instead automatically manage the webhook endpoint configuration on behalf of your users for any accounts that install your app—events will be sent to a centralized webhook endpoint you control (i.e. a public-facing URL). To get started, follow our guide on how to build an App using OAuth 2.0.

Here’s a video showing how this new onboarding flow should work in practice:

Readying your plugin for Workbench

I plan to use a template link and Workbench for my onboarding flow. How should I update my plugin?

1. Add a template link to your documentation to preconfigure a webhook endpoint for your users.

If your plugin requires your users to create a webhook endpoint, provide a template link, which uses URL-encoded query parameters to preselect necessary event types on behalf of your user— they will only need to provide the URL where webhook events should be delivered.

Rather than subscribing your plugin to all event types that Stripe provides, specify only the exact event types your plugin relies on. This prevents your plugin from needing to process extraneous events which could overwhelm your server with requests during traffic surges—and reduces your compute and processing costs for the additional load.

For example, including the following link in your onboarding experience or documentation to preselect the payment_intent.suceeded and charge.captured event types:

https://dashboard.stripe.com/workbench/webhooks/create?events=charge.captured%2Cpayment_intent.succeeded

To create a template link:

1. Use Workbench to create a new webhook endpoint.
2. Select the event types your plugin requires.
3. Copy the URL in your browser.

The URL in the browser will update to include the events types you selected as query parameters—and when visited, will redirect your user to either the Developer Dashboard or Workbench depending on their Stripe account configuration.

2. Update any screenshots showing the webhook creation flow in your documentation

If you provide screenshots showing your users how to create a webhook endpoint in Stripe Dashboard:

1. They should be updated to show the new creation flow in Workbench using the pre-configured template link.
2. If your existing users are not already using Workbench and need to update their webhook endpoint configuration, you can instruct them to enable it for their account by visiting dashboard.stripe.com/workbench.

Users will continue to be able to use the existing Developers view in the Dashboard for the next few months—once this rollout concludes, we will migrate all existing Stripe users to Workbench.

Post any questions, feedback, concerns on this topic in the thread below!