Bitbucket webhooks

Bitbucket Cloud webhooks are HTTP POST requests that Bitbucket sends to your URL when something you subscribe to happens in a repository or workspace, such as a push, a merged pull request or a build status change.

29 events covered 10 captured samples

These pages cover Bitbucket Cloud. Bitbucket Data Center is a separate self-managed product, with its own event keys, such as repo:refs_changed, and its own webhook docs.

How Bitbucket webhooks work

Webhooks let your systems react to Bitbucket as things happen, so you don't have to poll its API. A webhook belongs to a repository, and subscribes to one or more events, with a repository push as the default. The REST API also offers workspace webhooks, which fire for every repository in the workspace and can subscribe to 5 more events.

Each delivery is a POST with a JSON body. The X-Event-Key header names the event with a value such as repo:push, X-Hook-UUID identifies the webhook, and X-Attempt-Number counts the attempts. Most bodies carry actor and repository plus an object for the event, while pipeline:span_created is an OpenTelemetry trace. Bitbucket's docs name no version header or field for payloads.

Key facts

Signature header
X-Hub-Signature

Not every delivery is signed: check your setup.

Scheme
HMAC-SHA256
Signed material
{raw body}

The request body exactly as sent, with no timestamp or other data added.

How events are identified
x-event-key header
Body format
JSON

Content type: application/json.

Other headers
x-attempt-number, x-b3-sampled, x-b3-spanid, x-b3-traceid, x-event-key, x-event-time, x-hook-uuid, x-request-uuid
Envelope
actor, repository
Agent skill
npx skills add hookdeck/webhook-skills --skill bitbucket-webhooks

Verify Bitbucket webhooks →

Setting up Bitbucket webhooks

  • Create a webhook under Webhooks in the repository's settings, or with POST /2.0/repositories/{workspace}/{repo_slug}/hooks. Only repository administrators can create one, and a repository can have up to 50. Enter a secret or select Generate secret, and choose from the full list of triggers if you need more than pushes.
  • Test by triggering the real event, such as a push to a test repository. To receive it on your own machine, point the webhook at a tunnel such as the Hookdeck CLI.
  • To see what Bitbucket sent, select View requests on the webhook and then Enable history, which records new requests from that point. Bitbucket removed its Resend request button in 2021, so you can't resend a delivery by hand.

Delivery behaviour

  1. Failed deliveries can't be resent

    Bitbucket sends a delivery up to two more times after a 5xx, then stops, and it removed its Resend request button in 2021. Recover what you missed from the REST API.

    Retries and recovery →
  2. Slow handlers time out

    Bitbucket waits 10 seconds for a response, then the request times out. Its docs only name 5xx responses as retried, so return a 2xx straight away and process the event from a queue.

    Handle timeouts →
  3. A retry can repeat work

    If your handler does the work and then returns a 5xx, Bitbucket sends the event again with a higher X-Attempt-Number. Key your processing on what the event describes, such as a commit hash or a pull request ID.

    Handle duplicates →
  4. Large payloads may never be sent

    Bitbucket limits a webhook payload to 256 KB and says a webhook may silently fail to trigger when its payload is too large. Reconcile from the REST API if you depend on large changes.

    Other limits →

Bitbucket webhook best practices

Common Bitbucket webhook events

Code and builds

repo:push A push creates, updates or deletes a branch or tag
repo:commit_status_created A build tool reports a new commit status
repo:commit_status_updated A build tool changes an existing commit status

Pull requests

pullrequest:created Someone opens a pull request
pullrequest:updated Someone edits or updates a pull request
pullrequest:approved Reviewer approves a pull request
pullrequest:fulfilled Pull request gets merged
pullrequest:rejected Pull request gets declined

Comments and issues

pullrequest:comment_created New comment on a pull request
issue:created Someone files an issue
issue:comment_created Someone comments on an issue

Events by resource

Resource Events Payloads
pullrequest

pullrequest:created · :updated · :push · :changes_request_created +10

14 13
repo

repo:push · :fork · :updated · :transfer +6

10 7
issue

issue:created · :updated · :comment_created

3 3

1 more resource, including Other Bitbucket events. All 29 events →

In this hub

Webhook events → Every covered Bitbucket event, with payloads where the registry has them.
MCP events → How an agent subscribes to Bitbucket events as MCP events.
Verify signatures → Signature facts, verification code and common failures.
Production guide → Production problems: timeouts, duplicates, ordering and retries, and how to handle them.
Agent skill → Install the webhook skill in your coding agent. npx skills add hookdeck/webhook-skills --skill bitbucket-webhooks

Keep a short outage from costing you Bitbucket events.

Bitbucket retries a failing delivery twice, then stops, and you can't resend it. Hookdeck Event Gateway accepts every Bitbucket delivery, verifies the signature, queues events and retries to your service on your schedule.

Not affiliated with Bitbucket. Facts are compiled from public sources and linked inline.