Bitbucket webhooks notify your application about repository events, pull requests, and pipeline status changes. They support both Bitbucket Cloud and Bitbucket Server with slightly different event formats.
Bitbucket webhooks are HTTP POST requests that Bitbucket sends to your server when specific events occur in your account. Rather than continuously polling the Bitbucket API for updates, webhooks deliver real-time notifications the moment something happens — a payment completes, a user signs up, a deployment finishes, or any other tracked event.
Debugging these webhooks can be challenging because they originate from Bitbucket's servers, not your browser. You can't simply open DevTools to inspect them. That's where WebhookVault comes in — capture every Bitbucket webhook, inspect the full payload and headers, and replay them to your local development server.
| Event | Description |
|---|---|
| repo:push | Fired when commits are pushed to a repository |
| pullrequest:created | Fired when a new pull request is created |
| pullrequest:fulfilled | Fired when a pull request is merged |
| repo:commit_status_updated | Fired when a build status is updated |
Follow these steps to start capturing and debugging Bitbucket webhooks using WebhookVault.
Sign up for a free WebhookVault API key and create an endpoint to capture Bitbucket webhooks.
curl -X POST https://webhookvault.anethoth.com/api/v1/endpoints \
-H "Authorization: Bearer wv_your_key" \
-H "Content-Type: application/json" \
-d '{"name": "Bitbucket Webhooks"}'
# Response:
# {"url": "https://webhookvault.anethoth.com/hook/abc123", "inspect_url": "https://webhookvault.anethoth.com/inspect/abc123"}Go to your Bitbucket repository Settings > Webhooks Click 'Add webhook' and enter a title and your WebhookVault URL Select the triggers you want (Repository push, Pull request events, etc.) Save the webhook configuration
Once Bitbucket sends a webhook, you can inspect every detail through the WebhookVault API or web inspector.
curl https://webhookvault.anethoth.com/api/v1/endpoints/abc123/requests \
-H "Authorization: Bearer wv_your_key"
# Returns all captured Bitbucket webhook requests with full headers, body, and metadataReplay any captured Bitbucket webhook to your local development server for testing.
curl -X POST https://webhookvault.anethoth.com/api/v1/endpoints/abc123/requests/1/replay \
-H "Authorization: Bearer wv_your_key" \
-H "Content-Type: application/json" \
-d '{"url": "http://localhost:3000/webhook"}'
# The original Bitbucket webhook is replayed to your local serverHere is an example of a typical Bitbucket webhook payload. Use WebhookVault to capture real payloads from your Bitbucket account for accurate testing.
{
"push": {
"changes": [
{
"new": {
"name": "main",
"type": "branch",
"target": {
"hash": "abc123def456",
"message": "Fix critical bug",
"author": {
"raw": "John Doe <[email protected]>"
},
"date": "2024-01-15T10:30:00+00:00"
}
}
}
]
},
"repository": {
"full_name": "team/repo",
"uuid": "{abc-123}"
},
"actor": {
"display_name": "John Doe"
}
}Here are the most common issues developers encounter when working with Bitbucket webhooks, and how to resolve them.
Bitbucket Cloud webhooks don't include a signature header. Use IP allowlisting or a secret URL path for security.
Bitbucket uses colon-separated event keys (repo:push, pullrequest:created). Handle these in your routing logic.
Bitbucket Cloud and Bitbucket Server have different payload formats and available events.
Each webhook has a UUID. Use the X-Hook-UUID header to identify which webhook triggered the request.
Bitbucket webhooks are HTTP callbacks that Bitbucket sends to your server when specific events occur. Instead of polling the Bitbucket API for changes, webhooks push real-time notifications to your application, making your integration more efficient and responsive.
Use WebhookVault to capture Bitbucket webhooks in the cloud, then replay them to your localhost. Create a WebhookVault endpoint, configure Bitbucket to send webhooks to it, and use the replay API to forward captured requests to http://localhost:3000/webhook (or your local port).
Most webhook providers, including Bitbucket, sign their webhook payloads to prove authenticity. Check the Bitbucket documentation for the specific signature header and verification algorithm. Use WebhookVault to capture and inspect the raw headers to debug signature verification issues.
Unlike ngrok, WebhookVault captures and stores every webhook request with full headers and payloads. You can replay any Bitbucket webhook to your local server as many times as needed, inspect historical requests, and share webhook data with your team. No tunnel to maintain or port to expose.
Create a free WebhookVault endpoint in seconds. Capture, inspect, and replay Bitbucket webhooks with zero configuration.
Get Free API Key