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.
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
{raw body} The request body exactly as sent, with no timestamp or other data added.
x-attempt-number, x-b3-sampled, x-b3-spanid, x-b3-traceid, x-event-key, x-event-time, x-hook-uuid, x-request-uuid 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
10 seconds then the request times out, and the request log shows -1 Retries up to 2 more on a 5xx response. No interval or backoff is documented After retries no manual resend the button went in 2021, so recover from the REST API Duplicates possible on a retry X-Attempt-Number above 1 marks one. No event ID is documented Known failure modes
From Hookdeck's Bitbucket guide →-
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 → -
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 → -
A retry can repeat work
If your handler does the work and then returns a 5xx, Bitbucket sends the event again with a higher
Handle duplicates →X-Attempt-Number. Key your processing on what the event describes, such as a commit hash or a pull request ID. -
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
- Set a secret and verify every signature. Without a secret Bitbucket sends no signature, and anyone who finds your URL can send fake events to it.
- Respond within 10 seconds. Return a 2xx and process the event from a queue. After 10 seconds the request times out.
- Plan to recover missed events yourself. 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.
X-Attempt-Numberabove 1 marks a retry. Make handlers idempotent, keyed on what the event describes, such as a commit hash. - Subscribe only to what you process. 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.
repo:pushlists at most the 5 most recent commits for each ref. Whentruncatedis true, fetch the rest from the REST API.
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 | 14 | 13 |
repo | 10 | 7 |
issue | 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.