> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stackone.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Bitbucket Webhook Setup Guide

> Configure Bitbucket to deliver events to StackOne.

## Prerequisites

The connector should already be set up, with a Connector Profile and a Linked Account. See [Getting Started](/connectors/bitbucket#getting-started) on the Bitbucket connector page.

<section data-guide-section data-guide-scopes="">
  <h2>Automatic webhook subscription</h2>

  <p>StackOne creates and manages the Bitbucket webhook automatically. When webhook events are enabled for a connected account, StackOne creates one workspace-level webhook (named <strong>StackOne</strong>) in the workspace from the <strong>Webhook Workspace</strong> field, subscribed to the events you enable. It covers every repository in that workspace.</p>

  <Steps>
    <Step title="Grant the webhook permissions">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Edit your OAuth consumer under <strong>Workspace settings > OAuth consumers</strong> and make sure the webhook permissions are enabled before connecting the account.</p>

        <ul>
          <li><strong>OAuth 2.0 (Legacy)</strong> — enable <strong>Webhooks</strong> (Read and write)</li>
          <li><strong>OAuth 2.0 (Atlassian Identity Platform)</strong> — enable the webhook scopes (read, write, delete)</li>
          <li>Bitbucket only delivers events for resources the consumer can read, for example pull request events need the <strong>Pull requests</strong> permission</li>
        </ul>
      </div>
    </Step>

    <Step title="Set the Webhook Workspace">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>On the connected account, set <strong>Webhook Workspace</strong> to the workspace slug, the `{workspace}` segment of `https://bitbucket.org/{workspace}/`. The connecting user must be an administrator of this workspace.</p>
      </div>
    </Step>

    <Step title="Enable events in StackOne">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Select the webhook events you want in StackOne. StackOne registers the webhook with exactly those events. You can view it in Bitbucket under <strong>Workspace settings > Webhooks</strong>.</p>
      </div>
    </Step>

    <Step title="Changing or removing events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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.</p>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Available webhook events</h2>

  <p>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.</p>

  <Steps>
    <Step title="Repository events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to repositories, including pushes, forks, and settings changes. Events marked workspace-only are delivered because StackOne subscribes at the workspace level.</p>

        <ul>
          <li><strong>Repository Push</strong> (`repo:push`) — Fired when one or more commits, branches, or tags are pushed to a Bitbucket repository</li>
          <li><strong>Repository Forked</strong> (`repo:fork`) — Fired when a Bitbucket repository is forked</li>
          <li><strong>Repository Updated</strong> (`repo:updated`) — Fired when a repository's name, description, website, or language is changed</li>
          <li><strong>Repository Created</strong> (`repo:created`) — Fired when a new repository is created in the workspace. Workspace-level subscriptions only</li>
          <li><strong>Repository Deleted</strong> (`repo:deleted`) — Fired when a repository is hard-deleted from the workspace. Workspace-level subscriptions only</li>
          <li><strong>Repository Imported</strong> (`repo:imported`) — Fired when a repository import into the workspace completes. Workspace-level subscriptions only</li>
          <li><strong>Repository Transfer Accepted</strong> (`repo:transfer`) — Fired when a repository transfer into the workspace is accepted. Workspace-level subscriptions only</li>
        </ul>
      </div>
    </Step>

    <Step title="Commit events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to commit comments and build statuses reported by CI tools.</p>

        <ul>
          <li><strong>Commit Comment Created</strong> (`repo:commit_comment_created`) — Fired when a user comments on a commit in a repository</li>
          <li><strong>Build Status Created</strong> (`repo:commit_status_created`) — Fired when a CI system or app creates a build status on a commit</li>
          <li><strong>Build Status Updated</strong> (`repo:commit_status_updated`) — Fired when a CI system or app updates an existing build status on a commit</li>
        </ul>
      </div>
    </Step>

    <Step title="Project events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to workspace projects.</p>

        <ul>
          <li><strong>Project Updated</strong> (`project:updated`) — Fired when any field on a workspace project is updated. Workspace-level subscriptions only</li>
        </ul>
      </div>
    </Step>

    <Step title="Pull request events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to the pull request lifecycle and reviews.</p>

        <ul>
          <li><strong>Pull Request Created</strong> (`pullrequest:created`) — Fired when a new pull request is opened in a repository</li>
          <li><strong>Pull Request Updated</strong> (`pullrequest:updated`) — Fired when a pull request's title, description, reviewers, or destination branch is changed</li>
          <li><strong>Pull Request Pushed</strong> (`pullrequest:push`) — Fired when new commits are pushed to the source branch of an open pull request</li>
          <li><strong>Pull Request Approved</strong> (`pullrequest:approved`) — Fired when a user approves a pull request</li>
          <li><strong>Pull Request Approval Removed</strong> (`pullrequest:unapproved`) — Fired when a user removes their approval from a pull request</li>
          <li><strong>Pull Request Changes Requested</strong> (`pullrequest:changes_request_created`) — Fired when a reviewer sets Request changes on a pull request</li>
          <li><strong>Pull Request Changes Request Removed</strong> (`pullrequest:changes_request_removed`) — Fired when a reviewer removes their Request changes status from a pull request</li>
          <li><strong>Pull Request Merged</strong> (`pullrequest:fulfilled`) — Fired when a pull request is merged</li>
          <li><strong>Pull Request Declined</strong> (`pullrequest:rejected`) — Fired when a pull request is declined</li>
        </ul>
      </div>
    </Step>

    <Step title="Pull request comment events">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>Events related to comments on pull requests.</p>

        <ul>
          <li><strong>Pull Request Comment Created</strong> (`pullrequest:comment_created`) — Fired when a user comments on a pull request</li>
          <li><strong>Pull Request Comment Updated</strong> (`pullrequest:comment_updated`) — Fired when a user edits a comment on a pull request</li>
          <li><strong>Pull Request Comment Deleted</strong> (`pullrequest:comment_deleted`) — Fired when a user deletes a comment on a pull request</li>
          <li><strong>Pull Request Comment Resolved</strong> (`pullrequest:comment_resolved`) — Fired when a user resolves a comment thread on a pull request</li>
          <li><strong>Pull Request Comment Reopened</strong> (`pullrequest:comment_reopened`) — Fired when a user reopens a previously resolved comment thread on a pull request</li>
        </ul>
      </div>
    </Step>
  </Steps>
</section>

<section data-guide-section data-guide-scopes="">
  <h2>Delivery format</h2>

  <p>Details of how Bitbucket delivers events to StackOne.</p>

  <Steps>
    <Step title="One event per request">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>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.</p>
      </div>
    </Step>

    <Step title="Retries">
      <div data-guide-step data-guide-scopes="" data-guide-display-scopes-list="">
        <p>If a delivery fails, Bitbucket retries it up to two more times. The `X-Attempt-Number` header shows which attempt it is.</p>
      </div>
    </Step>
  </Steps>
</section>

## Verify

Your Connector should now be able to receive and process events. Try triggering an event and you should see an Event appear in the Connector logs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.