Book a demo

Event

trigger.bitbucket_event
TriggerBusiness appsconnection requiredruns in-engine

Registers a Bitbucket webhook on publish and starts one run per delivery, verified against X-Hub-Signature and deduped on X-Request-UUID.

Start a run on a Bitbucket Cloud event (push, pull request, issue).

Ask about BitbucketAll Bitbucket nodes

Connection

Required
Yes — the node will not save without one
Auth type
Username & password
Providers
Bitbucket
Secret shape
the app password, or {"app_password": "…"}
Config it needs
workspace, user
Resolved by
config.connection_id, else node.connection_id
Note
The app password needs the 'webhook' scope as well as the scope each subscribed event belongs to — 'repository' for repo:*, 'issue' for issue:*, 'pullrequest' for pullrequest:*. Publishing also needs MANTLE_APP_PUBLIC_BASE_URL set to a public https URL: Bitbucket refuses a hook whose url 'cannot be an internal, non-routed address'.

Configuration

2 fields, none required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

FieldTypeRequiredDefaultConstraintsExample
repo
Repository slug to watch, e.g. 'app'. Leave blank for a workspace-wide hook covering every repository in the connection's workspace.
stringNo—matches ^[A-Za-z0-9._-]+$—
events
Bitbucket event keys to subscribe to. repo:created, repo:deleted, repo:imported, repo:transfer and project:updated need a workspace-wide hook — leave 'repo' blank to use them.
arrayNo["repo:push"]1–29 characters; array of string—

Example configuration

Every value below is the contract’s own example or default — nothing invented.

{
  "events": [
    "repo:push"
  ]
}

Output

One shape.

bitbucket event

A flat envelope taken from Bitbucket's delivery headers and actor / repository blocks, with the body under `payload`. `payload` keys depend on event_key, so the shape is open below the declared fields.

Extra keys beyond the ones listed can appear.

FieldTypeExample
event_key
Bitbucket's event key (X-Event-Key), e.g. repo:push. Branch on this when the trigger subscribes to more than one event.
stringrepo:push
request_uuid
X-Request-UUID — Bitbucket's id for this delivery, and the run's idempotency key. Bitbucket retries a failed delivery twice more and the attempt counter, not this id, is what changes, so a retry joins the run it already started instead of starting a second.
stringa8f0b8cc-4b4c-4a0f-9a4e-0b39ba5a7f21
hook_uuid
X-Hook-UUID — which webhook subscription delivered this.
string{6c6b5f2a-1a3d-4e2b-9b8b-5f4e0d1c2b3a}
attempt_number
X-Attempt-Number: 1 on the first try, 2 or 3 on a retry.
number1
actor.display_name
The Bitbucket user who caused the event, or '' where the event has no actor.
stringOcto Cat
actor.account_id
That user's Atlassian account id.
string—
repository.full_name
workspace/repo-slug the event is about, or '' on a workspace event that names no repository.
stringacme/app
repository.uuid
The repository's Bitbucket uuid, braces included.
string—
payload
Bitbucket's webhook body exactly as it arrived — push changes, the pull request, the issue, the comment. Its keys depend on event_key.
object—
{
  "actor": {
    "account_id": "557058:6b1c9f3a",
    "display_name": "Octo Cat"
  },
  "attempt_number": 1,
  "event_key": "repo:push",
  "hook_uuid": "{6c6b5f2a-1a3d-4e2b-9b8b-5f4e0d1c2b3a}",
  "payload": {
    "push": {
      "changes": []
    }
  },
  "repository": {
    "full_name": "acme/app",
    "uuid": "{2f4b1c0d-9e8a-4f6b-8c7d-1a2b3c4d5e6f}"
  },
  "request_uuid": "a8f0b8cc-4b4c-4a0f-9a4e-0b39ba5a7f21"
}

Notes

  • The hook is created at publish and deleted on unpublish, disable or archive, so a workspace never keeps delivering to a workflow that is off.
  • Every delivery is verified against X-Hub-Signature (HMAC-SHA256 of the raw body) before a run can start; an unsigned or mis-signed POST gets a 401.
  • One run per X-Request-UUID — Bitbucket retries a failed delivery twice more and a retry joins the first run instead of starting another.
  • repo and events are read when the workflow is published, before any run exists, so neither can be a {{ expression }}.

Related Bitbucket nodes

Solutions with Bitbucket

See Event run in a workflow.

In a technical demo we add the Bitbucket connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.

Book a technical demoTalk to sales