Prerequisites
The connector should already be set up, with a Connector Profile and a Linked Account. See Getting Started on the Bitbucket connector page.Automatic webhook subscription
StackOne creates and manages the Bitbucket webhook automatically. When webhook events are enabled for a connected account, StackOne creates one workspace-level webhook (named StackOne) in the workspace from the Webhook Workspace field, subscribed to the events you enable. It covers every repository in that workspace.
Grant the webhook permissions
Edit your OAuth consumer under Workspace settings > OAuth consumers and make sure the webhook permissions are enabled before connecting the account.
- OAuth 2.0 (Legacy) — enable Webhooks (Read and write)
- OAuth 2.0 (Atlassian Identity Platform) — enable the webhook scopes (read, write, delete)
- Bitbucket only delivers events for resources the consumer can read, for example pull request events need the Pull requests permission
Set the Webhook Workspace
On the connected account, set Webhook Workspace to the workspace slug, the {workspace} segment of https://bitbucket.org/{workspace}/. The connecting user must be an administrator of this workspace.
Enable events in StackOne
Select the webhook events you want in StackOne. StackOne registers the webhook with exactly those events. You can view it in Bitbucket under Workspace settings > Webhooks.
Changing or removing events
Changing the event selection replaces the StackOne webhook with a new one for the updated event list. Disconnecting the account deletes the webhook, which stops deliveries.
Available webhook events
The following Bitbucket events can be enabled. Only events selected in StackOne are included in the webhook subscription — Bitbucket will not deliver events that are not subscribed.
Repository events
Events related to repositories, including pushes, forks, and settings changes. Events marked workspace-only are delivered because StackOne subscribes at the workspace level.
- Repository Push (
repo:push) — Fired when one or more commits, branches, or tags are pushed to a Bitbucket repository - Repository Forked (
repo:fork) — Fired when a Bitbucket repository is forked - Repository Updated (
repo:updated) — Fired when a repository’s name, description, website, or language is changed - Repository Created (
repo:created) — Fired when a new repository is created in the workspace. Workspace-level subscriptions only - Repository Deleted (
repo:deleted) — Fired when a repository is hard-deleted from the workspace. Workspace-level subscriptions only - Repository Imported (
repo:imported) — Fired when a repository import into the workspace completes. Workspace-level subscriptions only - Repository Transfer Accepted (
repo:transfer) — Fired when a repository transfer into the workspace is accepted. Workspace-level subscriptions only
Commit events
Events related to commit comments and build statuses reported by CI tools.
- Commit Comment Created (
repo:commit_comment_created) — Fired when a user comments on a commit in a repository - Build Status Created (
repo:commit_status_created) — Fired when a CI system or app creates a build status on a commit - Build Status Updated (
repo:commit_status_updated) — Fired when a CI system or app updates an existing build status on a commit
Project events
Events related to workspace projects.
- Project Updated (
project:updated) — Fired when any field on a workspace project is updated. Workspace-level subscriptions only
Pull request events
Events related to the pull request lifecycle and reviews.
- Pull Request Created (
pullrequest:created) — Fired when a new pull request is opened in a repository - Pull Request Updated (
pullrequest:updated) — Fired when a pull request’s title, description, reviewers, or destination branch is changed - Pull Request Pushed (
pullrequest:push) — Fired when new commits are pushed to the source branch of an open pull request - Pull Request Approved (
pullrequest:approved) — Fired when a user approves a pull request - Pull Request Approval Removed (
pullrequest:unapproved) — Fired when a user removes their approval from a pull request - Pull Request Changes Requested (
pullrequest:changes_request_created) — Fired when a reviewer sets Request changes on a pull request - Pull Request Changes Request Removed (
pullrequest:changes_request_removed) — Fired when a reviewer removes their Request changes status from a pull request - Pull Request Merged (
pullrequest:fulfilled) — Fired when a pull request is merged - Pull Request Declined (
pullrequest:rejected) — Fired when a pull request is declined
Pull request comment events
Events related to comments on pull requests.
- Pull Request Comment Created (
pullrequest:comment_created) — Fired when a user comments on a pull request - Pull Request Comment Updated (
pullrequest:comment_updated) — Fired when a user edits a comment on a pull request - Pull Request Comment Deleted (
pullrequest:comment_deleted) — Fired when a user deletes a comment on a pull request - Pull Request Comment Resolved (
pullrequest:comment_resolved) — Fired when a user resolves a comment thread on a pull request - Pull Request Comment Reopened (
pullrequest:comment_reopened) — Fired when a user reopens a previously resolved comment thread on a pull request
Delivery format
Details of how Bitbucket delivers events to StackOne.
One event per request
Bitbucket sends one event per HTTP POST with a JSON body. The event type is carried only in the X-Event-Key header (for example repo:push), and StackOne uses the ID of the changed record (repository UUID, pull request ID, comment ID, build status key, or project key) as the event ID, so it can be fetched with the matching API call.
Retries
If a delivery fails, Bitbucket retries it up to two more times. The X-Attempt-Number header shows which attempt it is.