# Bitbucket build failed notifications on your phone

> Get a High-priority push notification when a Bitbucket Pipelines build (or any build status on a commit) fails.

- Company: Bitbucket (https://www.justpush.io/recipes/bitbucket)
- Event: `repo:commit_status_updated` (Build status updated)
- Tags: Code hosting, Builds & CI
- Install: https://studio.justpush.io/recipes/bitbucket/build-failed
- Web page: https://www.justpush.io/recipes/bitbucket/build-failed

## Setup

1. Click Install in Studio and sign in. The recipe is added to your account and you get a personal webhook URL.
2. In your Bitbucket repository, open Repository settings > Webhooks and click Add webhook.
3. Enter a title and paste your webhook URL (shown in Studio after install) as the URL.
4. Under Triggers, pick Choose from a full list of triggers, tick Build status updated and save.
5. Under **Triggers**, tick **Build status updated**. Also tick **Build status created** if another CI tool reports builds straight as failed; it's safe to have both, since only the final state pushes. Only failed builds push by default. Add `?all=1` to the URL to also get a quiet push when a build succeeds:
6. ```
7. your webhook URL (shown in Studio after install)?all=1
8. ```
9. This covers Bitbucket Pipelines and any other tool that reports build statuses on commits (Jenkins, Bamboo, …). Stopped builds are ignored.
10. Bitbucket signs deliveries when you set a **Secret** (`X-Hub-Signature: sha256=…`), but JustPush doesn't check that signature yet, so keep your endpoint URL private.

## Code

Studio calls `handleRequest(request)` with the incoming webhook (`{ method, headers, body, query, raw }`) and sends the message object it returns. Returning `null` sends nothing.

```js
// Bitbucket → repo:commit_status_updated (build failed)
// Fires when a build status on a commit (Bitbucket Pipelines or another CI tool) turns FAILED.
// Add ?all=1 to the URL to also get a quiet push when a build succeeds.
// Docs: https://support.atlassian.com/bitbucket-cloud/docs/event-payloads/#Build-status-updated

// The build status events this recipe reads.
const EVENTS = ["repo:commit_status_updated", "repo:commit_status_created"]

// Header names can arrive in any case.
function header(request, name) {
    const headers = request.headers || {}
    const key = Object.keys(headers).find((k) => k.toLowerCase() === name)
    const value = key ? headers[key] : null
    return Array.isArray(value) ? value[0] : value
}

// Only link to real http(s) URLs.
function link(url, cta) {
    return typeof url === "string" && /^https?:\/\//.test(url) ? [{ cta, url }] : []
}

// Query flags such as ?all=1.
function flag(request, name) {
    return ["1", "true", "yes"].includes(String(request.query?.[name] ?? "").toLowerCase())
}

function handleRequest(request) {
    const body = request.body && typeof request.body === "object" ? request.body : {}
    const event = header(request, "x-event-key")
    const status = body.commit_status && typeof body.commit_status === "object" ? body.commit_status : null

    // Guard: only build status events. The header decides when it's there; the payload's
    // shape is the fallback (for example in Studio's Test runner).
    if ((event ? !EVENTS.includes(event) : false) || !status) {
        console.log(`Ignoring Bitbucket "${event ?? "unknown"}" event`)
        return null
    }

    // States are INPROGRESS, SUCCESSFUL, FAILED or STOPPED; only the end result matters.
    const failed = status.state === "FAILED"
    if (!failed && !(status.state === "SUCCESSFUL" && flag(request, "all"))) {
        console.log(`Skipping build state "${status.state ?? "unknown"}"`)
        return null
    }

    const name = status.name ?? "Build"
    const where = [body.repository?.full_name ?? body.repository?.name ?? "a repository", status.refname].filter(Boolean).join(" · ")
    // The commit message isn't in Bitbucket's documented payload; the description is. Skip a
    // description that only repeats the name ("Pipeline #562 for main failed").
    const message = typeof status.commit?.message === "string" ? status.commit.message.split("\n")[0].trim() : ""
    const described = typeof status.description === "string" && status.description && !status.description.startsWith(name)
    const what = message || (described ? status.description : null)
    const who = body.actor?.display_name ?? body.actor?.nickname

    return {
        title: failed ? `❌ ${name} failed` : `✅ ${name} passed`,
        message: where + (what ? ` — ${what}` : "") + (who ? ` (${who})` : ""),
        topic: "Bitbucket",
        priority: failed ? 1 : -1, // High for broken builds, Low for the optional success pushes
        buttons: link(status.url, "View build"),
    }
}
```

## Bitbucket repo:commit_status_updated webhook payload (sample)

```json
{
  "actor": {
    "type": "user",
    "uuid": "{d301aafa-d676-4ee0-88be-962be7417567}",
    "nickname": "janedoe",
    "account_id": "557058:00000000-0000-0000-0000-000000000000",
    "display_name": "Jane Doe"
  },
  "repository": {
    "name": "web",
    "type": "repository",
    "uuid": "{673a6070-3421-46c9-9d48-90745f7bfe8e}",
    "links": {
      "html": {
        "href": "https://bitbucket.org/acme/web"
      }
    },
    "full_name": "acme/web",
    "is_private": true
  },
  "commit_status": {
    "key": "{7f1c0d9e-2b44-4e0a-9d6c-2f1f5a7c3b11}",
    "url": "https://bitbucket.org/acme/web/pipelines/results/562",
    "name": "Pipeline #562 for main",
    "type": "build",
    "links": {
      "self": {
        "href": "https://api.bitbucket.org/2.0/repositories/acme/web/commit/9fec847784abb10b2fa567ee63b85bd238955d0e/statuses/build/%7B7f1c0d9e-2b44-4e0a-9d6c-2f1f5a7c3b11%7D"
      },
      "commit": {
        "href": "https://api.bitbucket.org/2.0/repositories/acme/web/commit/9fec847784abb10b2fa567ee63b85bd238955d0e"
      }
    },
    "state": "FAILED",
    "refname": "main",
    "created_on": "2026-09-28T09:12:03.547563+00:00",
    "updated_on": "2026-09-28T09:16:44.433108+00:00",
    "description": "Pipeline #562 for main failed"
  }
}
```

## FAQ

### Does this work on iPhone and Android?

Yes. Install the JustPush app from the App Store or Google Play and sign in. Every phone signed in to your account gets the notification.

### Do I need to write code?

No. Install the recipe in Studio, paste your webhook URL into Bitbucket and you are done. The code is there if you want to change the text, the sound or the buttons.

### Can I change what the notification says?

Yes. After install the recipe's code is yours. Edit it in Studio and test it against the sample payload before you save.

### What does it cost?

JustPush is free for 30 days. After that it's $19.99 a year, or $39.99 once. There is no extra charge for recipes.