Add support for the Webhook Endpoint resource

[remi-stripe]

cc @stripe/api-libraries

[remi-stripe]

r? @ob-stripe

[ob-stripe]

LGTM

[mintplugins]

@remi-stripe @ob-stripe I am attempting to set this up for a connected account (through Stripe Connect), but it is not working if I use a connected account's secret key.

Connected accounts failing to create webhook

Using the PHP SDK it is giving me this error:

Fatal error: Uncaught Stripe\Error\Permission: This application does not have the required permissions for this endpoint on account 'ACCOUNT_ID_REMOVED_BY_PHIL'. The required permissions are not available for use by Connect applications. in stripe/stripe-php/lib/ApiRequestor.php on line 187

I also tried doing the call directly through cURL on the command line using this call:

curl https://api.stripe.com/v1/webhook_endpoints \
  -u STRIPE_CONNECTED_ACCOUNT_SECRET_API_KEY_HERE: \
  -d url="https://example.com/my/webhook/endpoint" \
  -d enabled_events[]=* 

Which gives me this error:
You are not permitted to configure webhook endpoints on a connected account. Did you mean to create a Connect webhook on your account instead?

Platform accounts create webhook successfully

If I try to do the above for a Platform account, it creates the webhook without any issue or error.

Why this is important

Creating webhooks on stripe-connected accounts is a really crucial component, as it allows connected accounts to set up their webhooks without them needing to log into their Stripe Account. It takes away the element of human error.

It may not be the case for every Stripe Connect account, but in my case, the Platform account does not need to know about any events happening on connected accounts. Only the connected accounts themselves need to know, and that requires a webhook within the connected account, pointing at a unique url.

Can support for this be added to the Webhooks API?

[remi-stripe]

@mintplugins This is expected behaviour though and we block it on purpose. You should never add a webhook endpoint per connected account. You would add a Connect webhook endpoint at the platform level and dispatch those events yourself.

I understand what you're describing but I think it's an anti-pattern. Either you are a platform, and you handle that logic, or you're what we call a "plugin" where the code is hosted on the merchant's server in which case you would not use Connect and instead have the merchant use their own API keys to add the endpoint on their account.

[mintplugins]

Thanks for responding @remi-stripe. I think I understand what you mean.

From my perspective, it's unnecessary for my infrastructure to act as an in-between, when it is simply relaying event details. Also, it opens up security issues that don't need to exist, as there is no need for the Platform to be notified about these connected-account events. In fact, I'd rather the Platform never know.

Could one argue that the webhooks set up within the Stripe Dashboard, manually by the connected account owner, are the same anti-pattern? They report all events, even connected-to-platform events.

[remi-stripe]

They are not exactly the same anti-pattern. On our end we have no visibility into why this URL gets added ultimately but our expectation is that whomever adds a URL in the Dashboard owns the server associated with that URL.

I still don't fully understand the use case here where you act as a Platform but would not want to get events. Can you try and give me more details around what you are trying to do, why you act as a Connect Platform but still don't want that information? This does not align with what usually happens

[pippinsplugins]

@remi-stripe Our use case (I work with @mintplugins) is that we're not really acting as a platform, Stripe Connect is used exclusively for the authentication of a store with the store owner's Stripe account. We've used Stripe Connect to provide an OAuth flow instead of requiring store owners manually enter their API keys.

This is in the context of a self-hosted eCommerce store powered by Easy Digital Downloads.

Since we only use Stripe Connect for authentication, we don't act as a platform in the standard definition. The store owner still has a Standard Stripe account with full control over their data and events. This also means they need to create webhooks in their account for various events (refunds, paid invoices, etc). We would like to trigger a remote creation of the necessary webhooks from the store (not from our platform).

Does that help clarify?

[remi-stripe]

@pippinsplugins Would you be able to clarify why you are using Stripe Connect in this case though? It seems uncommon as an approach for a self hosted plugin. Would love to better understand the upside of this approach on your side.

[pippinsplugins]

We use it because it lets us send our users through an OAuth process to set up their Stripe account with their store instead of requiring the manual copy-paste of API keys.

It's a much better experience that's less prone to error and less intimidating for non-technical users.

[remi-stripe]

@pippinsplugins Thanks a lot for providing all those details. I talked about this internally and we do see how this could be useful in your case. This is fairly complex to do right though. The issue here is that the webhook endpoint would live in the connected account. In that case, it should (in theory) have the API version associated with that Stripe account instead of your platform. If we did this, it would be ~impossible for you to write a webhook handler that doesn't break on new API versions. Otherwise, we'd have to set a different API version on the endpoint (based on your app's). Updating your API version would automatically impact the webhook endpoints on all your connected accounts (And potentially break them since you wouldn't have updater your code.

There are ways to work around this, but this is not as easy as just unblocking the feature right now and it's something we'd need to think about in the long term.

In the meantime, I really think that the best approach is to have a Platform webhook.