Webhook Subscriptions Missing Documentation

Questions
1

I can’t seem to find any documentation that lists the OAuth Permission scopes for the Webhooks Subscription API.

Also, the Ruby SDK does not include any documentation on the Webhooks Subscription API, although I did find the code in the SDK.

2

Ok, so when I try to create a Webhook Subscription, I get the message -

AUTHENTICATION_ERROR - The merchant has not given your application sufficient permissions to do that. The merchant must authorize your application for the following scopes: DEVELOPER_APPLICATION_WEBHOOKS_WRITE (RuntimeError)

Ok. Fine. Let’s add that to the list of scopes that we need for OAuth and disconnect and reauthorize.

Guess what? There’s no prompt for the Webhooks permission, and I still can’t use the API.

Is this API available for use??? If so, how do I actually manage to use it?

BTW. I noticed that there are VENDOR_READ and VENDOR_WRITE scopes, but I hadn’t added them to my authorization list. However, it looks like you don’t even check that this permission has been granted because I’ve been able to read and write using the Vendor API without a problem.

Looks like you might have a bit of a security exposure there!

3

Hey @spiffybrian!

Thanks for checking out the new API!

A couple of things:

  1. Thanks for letting us know about the Ruby SDK, we’ll take a look!
  2. The API doesn’t use OAuth scopes in the traditional sense, because the webhook subscriptions are owned by the application and not any particular merchant, they can’t be delegated via OAuth. You need to call them using a PAT for the application you want to manage subscriptions for. We know this isn’t super clear in the docs right now, so we’re working on updating those. I also know the error message is a little misleading, and we’re looking at that as well.
  3. I’m not as familiar with the Vendor API and associated scopes, so I’ll leave that to some colleagues, but tag them in (@Bryan-Square)
4

A quick update – but looking at the Ruby SDK on github, I do see the docs; though we are missing from the front README, we’ll get that updated.

https://github.com/square/square-ruby-sdk/blob/master/doc/api/webhook-subscriptions.md is a direct link to the documentation

5

Thanks for bringing this to our attention. I’m looking into the scope issue. :slightly_smiling_face:

6

Hi Bryan, I am also trying to implement a use case where adding / removing webhooks for our customers using oauth integration inside our application.

Is there any update when Its possible to request for DEVELOPER_APPLICATION_WEBHOOKS_WRITE scope using oauth.

Thank you,
Mohammad.

7

With the Webhooks Subscriptions endpoints you only call it with your personal access token. It’s not used with OAuth access tokens. :slightly_smiling_face:

8

Hi Bryan,

Thank you for the fast reply. Is this feature in Square roadmap?

9

No plan to support it cause there’s no need for it. Your app is where the subscription is managed. This is why only your personal access token can make changes to it. The subscriptions that are configured in your application with work with all OAuth’d accounts :slightly_smiling_face: