Change Notice - Connect app webhooks to be restricted by scopes 1 July 2020

Summary

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 pullrequest scope in order to receive the pullrequest:updated webhook.

Will my app be impacted?

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 using the `*` catch-all

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 repository 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 specifying individual webhooks

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:

Remove the webhooks for which it does not have scopes.
Update the app’s scopes.

Note that this behavior will only happen for new installations of your app. Previous installations will continue to send the same webhooks.

List of webhooks and their required scopes

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
`deployment:completed`	`repository`
`deployment:pending`	`repository`
`deployment:started`	`repository`
`issue:comment_created`	`issue`
`issue:created`	`issue`
`issue:updated`	`issue`
`project:updated`	`project`
`pullrequest:approved`	`pullrequest`
`pullrequest:comment_created`	`pullrequest`
`pullrequest:comment_deleted`	`pullrequest`
`pullrequest:created`	`pullrequest`
`pullrequest:fulfilled`	`pullrequest`
`pullrequest:rejected`	`pullrequest`
`pullrequest:superseded`	`pullrequest`
`pullrequest:unapproved`	`pullrequest`
`pullrequest:updated`	`pullrequest`
`repo:branch_created`	`repository`
`repo:branch_deleted`	`repository`
`repo:commit_comment_created`	`repository`
`repo:commit_status_created`	`repository`
`repo:commit_status_updated`	`repository`
`repo:created`	`repository`
`repo:deleted`	`repository`
`repo:fork`	`repository`
`repo:imported`	`repository`
`repo:push`	`repository`
`repo:transfer`	`repository`
`repo:updated`	`repository`
`user:account_property_changed`	`account`

Updating app scopes

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.

Summary

webhooks will be sent according to app scope
* will send all webhooks allowed by the app scopes
individual webhooks will require the app to have the required scope for installation
apps in conflict with either need to remove webhooks or add scopes
adding scopes depends on whether or not the app has been registered