<!-- BusyBot node reference — https://busybot.net/tools/bitbucket-trigger/ -->

> Node: Bitbucket Trigger (`bitbucket_trigger`) · Webhook trigger · v1
> Category: Development · Credentials: Bitbucket API (`bitbucketApi`)
> Updated: 2026-08-16

# Bitbucket Trigger

> Trigger workflows from Bitbucket Cloud webhook events

## Overview

Receives webhook events from Bitbucket Cloud. Supports both workspace-level and repository-level event subscriptions including pushes, pull requests, issues, comments, pipelines, and more. Validates incoming webhooks by comparing the x-hook-uuid header against the registered webhook UUID. Outputs the raw Bitbucket event payload with event metadata.

**Category:** Development  
**Tool Name:** `bitbucket_trigger`  
**Version:** 1

**Appearance:** Icon: `si-bitbucket` | Color: `#0052cc`

## Node Type

**Trigger** — webhook (receives incoming HTTP callbacks)

## Input / Output

| Direction | Port(s) |
|-----------|--------|
| Input | None (trigger node) |
| Output | `Output` |

## Credentials

This tool requires **Bitbucket API** credentials.
See the [Credentials Guide](https://busybot.net/credentials/bitbucket-api/) for setup instructions.

### Resources

| Resource | Value |
|----------|-------|
| Repository | `repository` |
| Workspace | `workspace` |

### Parameters

#### Repository (`repository`)

Subscribes to events on one repository.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Workspace | `string` | Yes | — | The Bitbucket workspace slug to listen for events on. Supports expressions. |
| Repository | `string` | Yes | — | The Bitbucket repository slug to listen for events on. Supports expressions. |
| Events | `multiOptions` | Yes | `[]` | Which Bitbucket events to listen for. Select one or more event types. |
| | | | | Options: `repo:push`, `repo:fork`, `repo:updated`, `repo:transfer`, `repo:created`, `repo:deleted`, `repo:commit_comment_created`, `repo:commit_status_created`, `repo:commit_status_updated`, `issue:created`, `issue:updated`, `issue:comment_created`, `pullrequest:created`, `pullrequest:updated`, `pullrequest:approved`, `pullrequest:unapproved`, `pullrequest:fulfilled` (merged), `pullrequest:rejected` (declined), `pullrequest:comment_created`, `pullrequest:comment_updated`, `pullrequest:comment_deleted`, `pullrequest:changes_request_created`, `pullrequest:changes_request_removed`, `project:updated` |

#### Workspace (`workspace`)

Subscribes to events across every repository in the workspace.

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| Workspace | `string` | Yes | — | The Bitbucket workspace slug to listen for events on. Supports expressions. |
| Events | `multiOptions` | Yes | `[]` | Which Bitbucket events to listen for. Select one or more event types. |
| | | | | Options: `repo:push`, `repo:fork`, `repo:updated`, `repo:transfer`, `repo:created`, `repo:deleted`, `repo:commit_comment_created`, `repo:commit_status_created`, `repo:commit_status_updated`, `issue:created`, `issue:updated`, `issue:comment_created`, `pullrequest:created`, `pullrequest:updated`, `pullrequest:approved`, `pullrequest:unapproved`, `pullrequest:fulfilled` (merged), `pullrequest:rejected` (declined), `pullrequest:comment_created`, `pullrequest:comment_updated`, `pullrequest:comment_deleted`, `pullrequest:changes_request_created`, `pullrequest:changes_request_removed`, `project:updated` |

## Output Data

Each delivered event produces one output item carrying the Bitbucket payload exactly as sent. The shape depends on the event, and always includes `actor` (who caused it) and `repository` (where it happened); a push adds `push.changes[]`, a pull request event adds `pullrequest`, an issue event adds `issue`, and so on.

Four fields are added to every item:

- `_trigger` — always `bitbucket_webhook`
- `_timestamp` — ISO 8601 timestamp of when the request arrived
- `_webhookEvent` — the Bitbucket event key, e.g. `repo:push`
- `_webhookUuid` — the UUID of the Bitbucket webhook that delivered the event

Deliveries whose webhook UUID does not match the registered subscription are silently discarded.

Reference the payload downstream by expression, e.g. `{{ $json.repository.full_name }}` or `{{ $json.pullrequest.title }}`.

## Usage Examples

- Start a workflow when code is pushed to a Bitbucket repository
- Trigger a deployment when a pull request is merged
- Notify team when a new issue is created in Bitbucket
- Run CI checks when a pull request is opened
- Track pipeline build status changes

## Example Configuration

Monitor push and pull request events across every repository in a workspace:

```json
{
  "type": "bitbucket_trigger",
  "parameters": {
    "resource": "workspace",
    "workspace": "my-company",
    "events": [
      "repo:push",
      "pullrequest:created",
      "pullrequest:updated",
      "pullrequest:fulfilled"
    ]
  }
}
```

Monitor specific events on a single repository:

```json
{
  "type": "bitbucket_trigger",
  "parameters": {
    "resource": "repository",
    "workspace": "my-company",
    "repository": "my-project",
    "events": [
      "repo:push",
      "pullrequest:created"
    ]
  }
}
```

Monitor issue activity across a workspace:

```json
{
  "type": "bitbucket_trigger",
  "parameters": {
    "resource": "workspace",
    "workspace": "support-team",
    "events": [
      "issue:created",
      "issue:updated",
      "issue:comment_created"
    ]
  }
}
```

Trigger a CI/CD pipeline on pushes to one repository:

```json
{
  "type": "bitbucket_trigger",
  "parameters": {
    "resource": "repository",
    "workspace": "dev-team",
    "repository": "main-app",
    "events": ["repo:push"]
  }
}
```

Drive a code review workflow:

```json
{
  "type": "bitbucket_trigger",
  "parameters": {
    "resource": "workspace",
    "workspace": "engineering",
    "events": [
      "pullrequest:created",
      "pullrequest:approved",
      "pullrequest:fulfilled",
      "pullrequest:rejected"
    ]
  }
}
```

Watch repository administration across a workspace:

```json
{
  "type": "bitbucket_trigger",
  "parameters": {
    "resource": "workspace",
    "workspace": "admin-team",
    "events": [
      "repo:created",
      "repo:deleted",
      "repo:transfer",
      "repo:fork"
    ]
  }
}
```

### Trigger Behavior

- **Activation:** When the workflow is activated, a webhook endpoint is registered with the service.
- **Deactivation:** The webhook is automatically unregistered when the workflow is deactivated.
- **Payload:** The incoming webhook payload is parsed and output as workflow items.
- **Verification:** Supports signature verification where applicable.

## Tips

Receives Bitbucket Cloud webhook events. Configure the resource scope (workspace or repository), select the events to subscribe to, and provide your Bitbucket API credentials. The trigger validates incoming webhooks using the x-hook-uuid header.

- **Slugs, not display names.** Both **Workspace** and **Repository** take the URL slug — the lowercase, hyphenated segment from `bitbucket.org/{workspace}/{repository}`.
- **Workspace scope is required either way.** A repository subscription still needs the workspace slug, because that is how Bitbucket addresses the repository.
- **`project:updated` is a workspace-level event** and will not fire on a repository subscription.
- **Branch on the event.** One subscription can carry many event types; switch on `{{ $json._webhookEvent }}` when different events need different handling.
- **Deliveries are matched to the subscription.** Every request must carry the UUID of the webhook this node registered; anything else is discarded without starting the workflow.