# Bitbucket Cloud webhooks in production: duplicates, retries and timeouts

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

This guide covers the problems Bitbucket Cloud webhooks cause in production and how to handle each one. What Bitbucket sends and how it's signed is on the [Bitbucket webhooks](/webhooks/bitbucket) overview, every event type is on [Bitbucket webhook events](/webhooks/bitbucket/events), and signature verification code is on [Verify Bitbucket webhooks](/webhooks/bitbucket/verify).

Bitbucket Data Center is a separate self-managed product with its own event keys and [its own webhook docs](https://confluence.atlassian.com/bitbucketserver/manage-webhooks-938025878.html), and this guide doesn't apply to it.

## At a glance

| Problem | What to do | With Event Gateway |
| --- | --- | --- |
| [Timeouts](#timeouts) | Return a 2xx within 10 seconds; process in a background job | Accepts the delivery at once, then queues it for your service |
| [Retries and recovery](#retries) | Log what you receive; reconcile from the REST API after an outage | Accepts deliveries while your service is down, retries them and lets you replay them |
| [Duplicates](#duplicates) | Key processing on the event's content; make handlers idempotent | Drops repeats before they reach your handler |
| [Choosing events](#choosing-events) | Subscribe only to the events you process; filter branches yourself | Filters and routes events by type and content |
| [Testing](#testing) | Trigger real events; forward them to localhost with a CLI | Forwards to localhost and replays past events |
| [Other limits](#other-limits) | Plan for the 256 KB cap, truncated commit lists and traffic spikes | Keeps its own searchable log and delivers at a rate you set |

## Bitbucket webhook timeouts and slow handlers {#timeouts}

Return a 2xx within 10 seconds, then do the work in a background job.

**Why it happens:** Bitbucket waits 10 seconds for a response, and then the request times out. The request log shows `TIMEOUT` if the request timed out before connecting, and reports a client timeout as a response status of -1. Handlers that query a database, call other APIs or start a build before responding go over the limit, and cold starts on serverless platforms use up part of the 10 seconds.

Bitbucket's docs only name 5xx responses as retried, so don't count on a timed-out delivery being sent again.

**Fix it in your handler:**

1. Verify the signature and return a 2xx straight away.
2. Push the event onto a queue (Redis, RabbitMQ or SQS) and process it in a worker. See [why to process webhooks asynchronously](/webhooks/guides/why-implement-asynchronous-processing-webhooks).
3. Keep the request path free of calls to other services.

For more on the causes, see [how to solve Bitbucket webhook timeout errors](/webhooks/platforms/how-to-solve-bitbucket-webhook-timeout-errors).

**With Event Gateway:** Hookdeck accepts each Bitbucket delivery immediately, then queues events and delivers them to your service at a rate you set, with its own retries. Your handler can take as long as it needs without failing a Bitbucket delivery.

## Bitbucket webhook retries and recovery {#retries}

Bitbucket retries a delivery up to twice and won't send it again after that, so plan to recover missed events yourself.

**Why it happens:** If your response is in the 500 to 599 range, Bitbucket automatically resends the request up to two more times. The docs give no interval or backoff between attempts. Atlassian [removed the Resend request button in 2021](https://confluence.atlassian.com/cloud/blog/2021/02/atlassian-cloud-changes-feb-1-to-feb-8-2021), and the REST API documents no way to resend a delivery. A short outage can use up all three attempts. For more on this problem, see [webhook delivery guarantees](/webhooks/guides/webhook-delivery-guarantees).

**Fix it in your handler:**

1. Keep your endpoint highly available, with a load balancer and health checks, and monitor its uptime. Bitbucket's docs describe no alert for failed deliveries, so alert from your own logs.
2. Return a 5xx only when you want Bitbucket to try again, because it's the only response the docs say is retried.
3. Store each payload as it arrives, so you can reprocess it yourself if a worker fails.
4. After an outage, reconcile from the REST API, for example with `GET /2.0/repositories/{workspace}/{repo_slug}/commits` and `GET /2.0/repositories/{workspace}/{repo_slug}/pullrequests`.

**With Event Gateway:** Hookdeck accepts deliveries while your service is down, retries them on a schedule you configure, and lets you replay any event, individually or in bulk, once you've recovered.

## Handling duplicate Bitbucket webhooks {#duplicates}

A retry repeats a delivery, so make handlers idempotent and key them on what the event describes.

**Why it happens:** If your handler does the work and then returns a 5xx, Bitbucket sends the same event again, and your work runs twice. `X-Attempt-Number` tells you how many times Bitbucket has tried. The docs describe `X-Request-UUID` only as the UUID of the request and don't say whether a retry keeps it, and they document no event ID.

**Fix it in your handler:**

1. Treat a delivery with `X-Attempt-Number` above 1 as one you may already have processed.
2. Build an idempotency key from the body: the commit hash and branch from `push.changes` on a push, or the pull request `id` and `updated_on` on a pull request event.
3. Record each key in a store with a unique constraint, in the same transaction as your changes. See [how to implement webhook idempotency](/webhooks/guides/implement-webhook-idempotency).

**With Event Gateway:** Hookdeck [deduplicates](/docs/deduplication) events before they reach your endpoint, so repeats are filtered at the infrastructure level rather than in each handler.

## Choosing which Bitbucket events to listen to {#choosing-events}

Subscribe each webhook only to the events your integration processes, and filter the rest in your handler.

**Why it matters:** A new webhook gets repository pushes only, so anything else stays silent until you select it. Selecting too much has its own cost: Bitbucket filters by event type and the docs describe no filter on content, so a webhook on `repo:push` gets every branch. The full list, with sample payloads, is on [Bitbucket webhook events](/webhooks/bitbucket/events).

**Fix it in your handler:**

1. Select Choose from a full list of triggers when you create the webhook, and pick exactly the events you handle.
2. Branch on the `X-Event-Key` header. A merge arrives as `pullrequest:fulfilled` and a decline as `pullrequest:rejected`. Keys such as `pr:merged` belong to Data Center, and Bitbucket Cloud doesn't send them.
3. Filter by branch in your own code, using `push.changes[].new.name`, and return a 2xx for what you skip.
4. Use a workspace webhook for `repo:transfer`, `repo:deleted`, `repo:created`, `repo:imported` and `project:updated`. Bitbucket's API lists those as valid only for workspace webhooks, which you create with `POST /2.0/workspaces/{workspace}/hooks`.

**With Event Gateway:** Hookdeck [filters](/docs/filters) and routes events on headers or body, so you can match on the branch or event type and let one Bitbucket webhook feed several services.

## Testing and debugging Bitbucket webhooks locally {#testing}

Trigger real events in a test repository, and forward them to your local server through a tunnel rather than deploying to test.

**Why it matters:** Bitbucket Cloud can't reach a server on your machine, and its docs describe no button for sending a test event, so a real action is the way to fire one.

**How to test:**

1. Point the webhook at a tunnel, then trigger the event, for example by pushing to a test repository. Bitbucket's [webhook tutorial](https://support.atlassian.com/bitbucket-cloud/docs/create-and-trigger-a-webhook-tutorial/) does this with ngrok.
2. Enable history before you need it. Under Repository settings > Webhooks > View requests, select Enable history. Bitbucket only records requests from then on, and you do this for each webhook. Atlassian [extended the history window to 1 week in 2021](https://confluence.atlassian.com/cloud/blog/2021/02/atlassian-cloud-changes-feb-1-to-feb-8-2021), and its current docs state no period.
3. Read the outcome in the request log: an HTTP status code, `TIMEOUT` or `NETWORK ERROR`. View details shows the payload, the headers and each attempt.
4. Check the webhook's URL if nothing arrives. It can't contain spaces or characters like `<>^`, and an `@` in a username has to be encoded as `%40`.
5. Keep fixtures of real payloads for edge cases; [Bitbucket webhook events](/webhooks/bitbucket/events) has sample payloads to start from.

**With Event Gateway:** The [Hookdeck CLI](/docs/cli) receives webhooks on your machine without a public server, and you can replay past events with one click, which Bitbucket no longer offers.

## Other Bitbucket webhook limits {#other-limits}

Plan for Bitbucket's payload cap, truncated commit lists and uneven traffic before they reach production.

**256 KB payload cap.** A payload is limited to 256 KB, and Bitbucket says a webhook may silently fail to trigger if its payload is too large, so no failed delivery appears at your endpoint. Treat the webhook as a notification and fetch full details from the REST API.

**Truncated commit lists.** `repo:push` lists up to the 5 most recent commits for each ref, and sets `truncated` to true when there are more. The list can also include commits that were already pushed to another ref, so don't count them as new.

**Null references on a push.** `new` is null when a branch is deleted, and `old` is null when one is created. A handler that reads `push.changes[].new.name` without checking fails on those pushes.

**Skipped comment edits.** If someone edits a pull request comment twice in quick succession, Bitbucket only sends `pullrequest:comment_updated` for the first edit, so your copy of the comment can go stale.

**Late deletion events.** `repo:deleted` fires on hard deletion, which can come 30 days after the repository was deleted.

**Traffic spikes.** Bitbucket's docs describe no setting to slow deliveries, so bulk operations can reach your endpoint all at once. Buffer them in a queue and apply backpressure in your workers.

**Webhook and certificate limits.** A repository can have up to 50 webhooks, so consolidate where you can by having one endpoint handle several event types. An HTTPS endpoint needs a valid certificate from a public certificate authority, and Atlassian advises against the Skip certificate verification option.

**With Event Gateway:** Hookdeck logs every event and delivery attempt, with the full request and response, delivers at a rate you set, and can fan one Bitbucket webhook out to several destinations. It can't make Bitbucket send a webhook that exceeds its payload cap. See [webhook observability architecture](/webhooks/guides/webhook-observability-architecture) if you're building this yourself.