# 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.

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](https://confluence.atlassian.com/bitbucketserver/manage-webhooks-938025878.html).

Agent skill: `npx skills add hookdeck/webhook-skills --skill bitbucket-webhooks` ([details](https://hookdeck.com/webhooks/bitbucket/skill))

> Independent reference generated from hookdeck/webhook-registry (commit a24c8d9, 19 Nov 2026). [Bitbucket's official docs](https://support.atlassian.com/bitbucket-cloud/docs/event-payloads/).

[Overview](https://hookdeck.com/webhooks/bitbucket) · [Webhook events (29)](https://hookdeck.com/webhooks/bitbucket/events) · [MCP events](https://hookdeck.com/webhooks/bitbucket/mcp-events) · [Verify signatures](https://hookdeck.com/webhooks/bitbucket/verify) · [Production guide](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts) · [Agent skill](https://hookdeck.com/webhooks/bitbucket/skill)

## Key facts

| Fact | Value | Source |
|---|---|---|
| Signature header | `X-Hub-Signature` Not every delivery is signed: check your setup. | [Bitbucket docs](https://support.atlassian.com/bitbucket-cloud/docs/manage-webhooks/) |
| Scheme | `HMAC-SHA256` | [Bitbucket docs](https://support.atlassian.com/bitbucket-cloud/docs/manage-webhooks/) |
| Signed material | `{raw body}` The request body exactly as sent, with no timestamp or other data added. | [Bitbucket docs](https://support.atlassian.com/bitbucket-cloud/docs/manage-webhooks/) |
| How events are identified | `x-event-key header` | [Bitbucket docs](https://support.atlassian.com/bitbucket-cloud/docs/event-payloads/) |
| Body format | `JSON` Content type: application/json. | [Registry record](https://hookdeck.com/webhooks/bitbucket.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` | [Registry record](https://hookdeck.com/webhooks/bitbucket.json) |
| Envelope | `actor, repository` | [Bitbucket docs](https://support.atlassian.com/bitbucket-cloud/docs/event-payloads/) |
| Agent skill | `npx skills add hookdeck/webhook-skills --skill bitbucket-webhooks` | [Agent skill →](https://hookdeck.com/webhooks/bitbucket/skill) |

[Verify Bitbucket webhooks](https://hookdeck.com/webhooks/bitbucket/verify)

## 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.

## 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](/docs/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](https://confluence.atlassian.com/cloud/blog/2021/02/atlassian-cloud-changes-feb-1-to-feb-8-2021), so you can't resend a delivery by hand.

## Delivery behaviour

- **Timeout:** 10 seconds. then the request times out, and the request log shows -1. [Guide](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#timeouts)
- **Retries:** up to 2 more. on a 5xx response. No interval or backoff is documented. [Guide](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#retries)
- **After retries:** no manual resend. the button went in 2021, so recover from the REST API. [Guide](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#retries)
- **Duplicates:** possible on a retry. `X-Attempt-Number` above 1 marks one. No event ID is documented. [Guide](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#duplicates)

## Known failure modes

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](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#retries)
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](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#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](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#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](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#other-limits)

From [Hookdeck's Bitbucket guide](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts).

## Bitbucket webhook best practices

- **[Set a secret and verify every signature](https://hookdeck.com/webhooks/bitbucket/verify).** Without a secret Bitbucket sends no signature, and anyone who finds your URL can send fake events to it.
- **[Respond within 10 seconds](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#timeouts).** Return a 2xx and process the event from a queue. After 10 seconds the request times out.
- **[Plan to recover missed events yourself](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#retries).** Bitbucket retries a 5xx up to twice more, then stops, and has no resend button. Reconcile from the REST API after an outage.
- **[Expect retries to repeat work](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#duplicates).** `X-Attempt-Number` above 1 marks a retry. Make handlers idempotent, keyed on what the event describes, such as a commit hash.
- **[Subscribe only to what you process](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#choosing-events).** A new webhook gets pushes only. Pick the events you handle, and filter by branch in your own code, because the docs describe no branch filter.
- **[Check `truncated` on pushes](https://hookdeck.com/webhooks/bitbucket/guide-duplicates-retries-timeouts#other-limits).** `repo:push` lists at most the 5 most recent commits for each ref. When `truncated` is true, fetch the rest from the REST API.

## Common Bitbucket webhook events

### Code and builds

- [repo:push](https://hookdeck.com/webhooks/bitbucket/events#repo%3Apush): A push creates, updates or deletes a branch or tag
- [repo:commit_status_created](https://hookdeck.com/webhooks/bitbucket/events#repo%3Acommit_status_created): A build tool reports a new commit status
- [repo:commit_status_updated](https://hookdeck.com/webhooks/bitbucket/events#repo%3Acommit_status_updated): A build tool changes an existing commit status

### Pull requests

- [pullrequest:created](https://hookdeck.com/webhooks/bitbucket/events#pullrequest%3Acreated): Someone opens a pull request
- [pullrequest:updated](https://hookdeck.com/webhooks/bitbucket/events#pullrequest%3Aupdated): Someone edits or updates a pull request
- [pullrequest:approved](https://hookdeck.com/webhooks/bitbucket/events#pullrequest%3Aapproved): Reviewer approves a pull request
- [pullrequest:fulfilled](https://hookdeck.com/webhooks/bitbucket/events#pullrequest%3Afulfilled): Pull request gets merged
- [pullrequest:rejected](https://hookdeck.com/webhooks/bitbucket/events#pullrequest%3Arejected): Pull request gets declined

### Comments and issues

- [pullrequest:comment_created](https://hookdeck.com/webhooks/bitbucket/events#pullrequest%3Acomment_created): New comment on a pull request
- [issue:created](https://hookdeck.com/webhooks/bitbucket/events#issue%3Acreated): Someone files an issue
- [issue:comment_created](https://hookdeck.com/webhooks/bitbucket/events#issue%3Acomment_created): Someone comments on an issue

## Events by resource

| Resource | Events | Payloads |
|---|---|---|
| [pullrequest](https://hookdeck.com/webhooks/bitbucket/events#resource-pullrequest) | 14 | 13 |
| [repo](https://hookdeck.com/webhooks/bitbucket/events#resource-repo) | 10 | 7 |
| [issue](https://hookdeck.com/webhooks/bitbucket/events#resource-issue) | 3 | 3 |

1 more resource. [All 29 events](https://hookdeck.com/webhooks/bitbucket/events)

## In this hub

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

Not affiliated with Bitbucket. Facts are compiled from public sources and linked inline. [View as JSON](https://hookdeck.com/webhooks/bitbucket.json) · [Report a correction](https://hookdeck.com/contact)
