Bitbucket is making a change that may result in connect apps receiving fewer webhooks than they were previously. We are doing this to provide end-users with more information about the type of access an app may have to their content. This could potentially break applications—read on to determine if your app will be impacted.
Previously, apps could register for any Bitbucket webhook, regardless of its scopes. Scopes were only applied to the API requests that the app made, not the webhooks it received—and this is what we’re changing.
We will begin enforcing the same scopes that are applied to API requests to webhooks as well. For example, your app will need to have the scope in order to receive the webhook.
Take a look at the webhooks that your app creates. Note that apps can list specific webhooks or use to indicate all webhooks. The required scope for each webhook is listed in the table below. The new behavior of your app will depend on which method you’re using to create webhooks.
If your app is creating webhooks with the catch-all, the webhooks that your app will receive will be filtered by the scopes for your app. For example, if your app has webhooks but only the scope, it will only receive webhooks for repository events. The new behavior will only apply to new installations, prior installations will keep receiving all webhooks.
Your app could work fine depending on which webhooks it requires to function appropriately. It may be that the webhooks that will be filtered out aren’t required for your app to function. In which case, you don’t need to make any changes.
If, however, you determine that your app doesn’t have the necessary scopes for the webhooks it needs, you’ll need to update its scopes.
If the your app specifies individual webhooks and it doesn’t have the required scopes for them, the app installation will fail. To reconcile this you have two options:
Note that this behavior will only happen for new installations of your app. Previous installations will continue to send the same webhooks.
Keep in mind that “write” scopes imply the equivalent “read” scope. As webhooks cannot write data, they will only ever require read-level scopes.
|Webhook||Minimum Required Scope|
Updating app scopes ultimately requires end-user consent. How you request consent depends on how the app was created.
If it is an app that has been registered in the “Develop apps” setting section, Bitbucket will automatically send emails to existing users asking for them to re-approve the app with its new scopes. All you need to do is 1) update your app’s descriptor and 2) click “update” for your app in the “Develop apps” section.
If your app hasn’t been registered in the “Develop apps” setting section, the only way to update scopes is to have users uninstall and re-install the app. It is possible for apps to uninstall themselves with this API but users will need install your new app from scratch in order to approve any scope change.