How to Test Bitbucket Webhooks

What Bitbucket Sends

Bitbucket webhooks send one event per POST request — no batching. The event type is identified by the X-Event-Key header, not a field in the body. Always read the header to route events in your handler.

Step 1 — Generate a Requex Endpoint

Open requex.me and copy your unique URL:

https://requex.me/hook/a1b2c3d4-e5f6-7890-abcd-ef1234567890

Step 2 — Configure Bitbucket Webhook

1. In Bitbucket Cloud, open your repository and go to Repository Settings (gear icon).
2. In the left sidebar, find Webhooks under the Workflow section.
3. Click Add webhook.
4. Give the webhook a title (e.g., "Requex Dev Test").
5. Paste your Requex URL into the URL field.
6. Leave Status as Active.
7. Under Triggers, select the events you want. For most use cases, start with Repository → Push, Pull Requests → Created and Fulfilled.
8. Click Save. Bitbucket will immediately fire a test ping event — you'll see it arrive in Requex.

Step 3 — Trigger a Test Event

Push a commit to any branch in the repository:

git commit --allow-empty -m "test: trigger Bitbucket webhook"
git push origin main

This fires a repo:push event. To test pull request events, create a branch, push it, and open a PR in the Bitbucket UI. The pullrequest:created event fires as soon as you submit the PR form.

Step 4 — Inspect the Payload

In Requex, click the incoming request and check both the Body and Headers tabs. A repo:push payload looks like:

// Headers — always check these first
X-Event-Key: repo:push
X-Request-UUID: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Content-Type: application/json

// Body
{
  "actor": {
    "type": "user",
    "display_name": "Jane Smith",
    "account_id": "5b1234abc"
  },
  "repository": {
    "type": "repository",
    "name": "my-repo",
    "full_name": "myteam/my-repo",
    "links": { "html": { "href": "https://bitbucket.org/myteam/my-repo" } }
  },
  "push": {
    "changes": [
      {
        "new": {
          "type": "branch",
          "name": "main",
          "target": {
            "hash": "abc123def456",
            "message": "test: trigger Bitbucket webhook",
            "author": { "raw": "Jane Smith <jane@example.com>" },
            "date": "2026-04-05T12:00:00+00:00"
          }
        },
        "old": { "name": "main", "target": { "hash": "xyz789" } },
        "created": false,
        "forced": false
      }
    ]
  }
}

The X-Request-UUID header provides a unique delivery ID useful for deduplication. The push.changes array lists every ref that changed in the push — a single push to multiple branches results in multiple entries.

Bitbucket Security — No Signature on Cloud

Bitbucket Cloud does not add an HMAC signature header by default. This is a key difference from GitHub (which signs with X-Hub-Signature-256) and GitLab (which uses X-Gitlab-Token).

https://yourapp.com/webhooks/bitbucket?secret=my-random-token-here

Common Issues