Bitbucket Cloud webhooks in production: duplicates, retries and timeouts

Published · Updated

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 overview, every event type is on Bitbucket webhook events, and signature verification code is on Verify Bitbucket webhooks.

Bitbucket Data Center is a separate self-managed product with its own event keys and its own webhook docs, and this guide doesn't apply to it.

At a glance

ProblemWhat to doWith Event Gateway
TimeoutsReturn a 2xx within 10 seconds; process in a background jobAccepts the delivery at once, then queues it for your service
Retries and recoveryLog what you receive; reconcile from the REST API after an outageAccepts deliveries while your service is down, retries them and lets you replay them
DuplicatesKey processing on the event's content; make handlers idempotentDrops repeats before they reach your handler
Choosing eventsSubscribe only to the events you process; filter branches yourselfFilters and routes events by type and content
TestingTrigger real events; forward them to localhost with a CLIForwards to localhost and replays past events
Other limitsPlan for the 256 KB cap, truncated commit lists and traffic spikesKeeps its own searchable log and delivers at a rate you set

Bitbucket webhook timeouts and slow handlers

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.
  3. Keep the request path free of calls to other services.

For more on the causes, see 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

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

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

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.

With Event Gateway: Hookdeck deduplicates 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

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.

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

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 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, 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 has sample payloads to start from.

With Event Gateway: The Hookdeck 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

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 if you're building this yourself.

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.