Get started

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.

Install in Studio See the setup
repo:commit_status_updatedCode hostingBuilds & CI
How it works

Three steps to your first push

STEP 01

Install the recipe

One click in Studio gives you a personal webhook URL.

STEP 02

Paste your URL into Bitbucket

Add it as a webhook for Build status updated.

STEP 03

Get a push on your phone

With the text, sound and buttons from the recipe.

Setup

How to set up the Bitbucket build status updated webhook

  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 as the URL.https://••••••••/•••••••• your personal URL, shown after install
  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?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.
The code

What runs when the webhook arrives

Studio calls handleRequest(request) with the incoming webhook and sends the message it returns. It's yours after install; change anything.

transform.js
1// Bitbucket → repo:commit_status_updated (build failed)
2// Fires when a build status on a commit (Bitbucket Pipelines or another CI tool) turns FAILED.
3// Add ?all=1 to the URL to also get a quiet push when a build succeeds.
4// Docs: https://support.atlassian.com/bitbucket-cloud/docs/event-payloads/#Build-status-updated
5
6// The build status events this recipe reads.
7const EVENTS = ["repo:commit_status_updated", "repo:commit_status_created"]
8
9// Header names can arrive in any case.
10function header(request, name) {
11 const headers = request.headers || {}
12 const key = Object.keys(headers).find((k) => k.toLowerCase() === name)
13 const value = key ? headers[key] : null
14 return Array.isArray(value) ? value[0] : value
15}
16
17// Only link to real http(s) URLs.
18function link(url, cta) {
19 return typeof url === "string" && /^https?:\/\//.test(url) ? [{ cta, url }] : []
20}
21
22// Query flags such as ?all=1.
23function flag(request, name) {
24 return ["1", "true", "yes"].includes(String(request.query?.[name] ?? "").toLowerCase())
25}
26
27function handleRequest(request) {
28 const body = request.body && typeof request.body === "object" ? request.body : {}
29 const event = header(request, "x-event-key")
30 const status = body.commit_status && typeof body.commit_status === "object" ? body.commit_status : null
31
32 // Guard: only build status events. The header decides when it's there; the payload's
33 // shape is the fallback (for example in Studio's Test runner).
34 if ((event ? !EVENTS.includes(event) : false) || !status) {
35 console.log(`Ignoring Bitbucket "${event ?? "unknown"}" event`)
36 return null
37 }
38
39 // States are INPROGRESS, SUCCESSFUL, FAILED or STOPPED; only the end result matters.
40 const failed = status.state === "FAILED"
41 if (!failed && !(status.state === "SUCCESSFUL" && flag(request, "all"))) {
42 console.log(`Skipping build state "${status.state ?? "unknown"}"`)
43 return null
44 }
45
46 const name = status.name ?? "Build"
47 const where = [body.repository?.full_name ?? body.repository?.name ?? "a repository", status.refname].filter(Boolean).join(" · ")
48 // The commit message isn't in Bitbucket's documented payload; the description is. Skip a
49 // description that only repeats the name ("Pipeline #562 for main failed").
50 const message = typeof status.commit?.message === "string" ? status.commit.message.split("\n")[0].trim() : ""
51 const described = typeof status.description === "string" && status.description && !status.description.startsWith(name)
52 const what = message || (described ? status.description : null)
53 const who = body.actor?.display_name ?? body.actor?.nickname
54
55 return {
56 title: failed ? `❌ ${name} failed` : `✅ ${name} passed`,
57 message: where + (what ? ` — ${what}` : "") + (who ? ` (${who})` : ""),
58 topic: "Bitbucket",
59 priority: failed ? 1 : -1, // High for broken builds, Low for the optional success pushes
60 buttons: link(status.url, "View build"),
61 }
62}
Payload

The Bitbucket repo:commit_status_updated webhook

This is what Bitbucket sends to your URL for build status updated. It is a sample, trimmed to the fields recipes use.

repo:commit_status_updated · sample.json
1{
2 "actor": {
3 "type": "user",
4 "uuid": "{d301aafa-d676-4ee0-88be-962be7417567}",
5 "nickname": "janedoe",
6 "account_id": "557058:00000000-0000-0000-0000-000000000000",
7 "display_name": "Jane Doe"
8 },
9 "repository": {
10 "name": "web",
11 "type": "repository",
12 "uuid": "{673a6070-3421-46c9-9d48-90745f7bfe8e}",
13 "links": {
14 "html": {
15 "href": "https://bitbucket.org/acme/web"
16 }
17 },
18 "full_name": "acme/web",
19 "is_private": true
20 },
21 "commit_status": {
22 "key": "{7f1c0d9e-2b44-4e0a-9d6c-2f1f5a7c3b11}",
23 "url": "https://bitbucket.org/acme/web/pipelines/results/562",
24 "name": "Pipeline #562 for main",
25 "type": "build",
26 "links": {
27 "self": {
28 "href": "https://api.bitbucket.org/2.0/repositories/acme/web/commit/9fec847784abb10b2fa567ee63b85bd238955d0e/statuses/build/%7B7f1c0d9e-2b44-4e0a-9d6c-2f1f5a7c3b11%7D"
29 },
30 "commit": {
31 "href": "https://api.bitbucket.org/2.0/repositories/acme/web/commit/9fec847784abb10b2fa567ee63b85bd238955d0e"
32 }
33 },
34 "state": "FAILED",
35 "refname": "main",
36 "created_on": "2026-09-28T09:12:03.547563+00:00",
37 "updated_on": "2026-09-28T09:16:44.433108+00:00",
38 "description": "Pipeline #562 for main failed"
39 }
40}
FAQ

Bitbucket build failed notifications: questions

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.

More recipes

More from Bitbucket

Bitbucket

Pull request

Get a push notification when a Bitbucket pull request is opened, approved, gets a change request or a comment, or is merged.

pullrequest:createdButtons

All 2 Bitbucket recipes

Builds & CI

More builds & ci recipes

App Store Connect

Build processing

Get a push notification when a build you uploaded finishes processing in App Store Connect, or fails.

BUILD_UPLOAD_STATE_UPDATEDButtons
Bitrise

Build finished

Get a High-priority push notification when a Bitrise build fails, and optionally a quiet one when it passes.

build/finishedButtons
Buildkite

Build failing

Get an early High-priority push notification the moment a Buildkite build starts failing, while its other jobs are still running.

build.failingButtons

All builds & ci recipes

Ready when you are

Bitbucket on your phone in two minutes.

Install the recipe, paste one URL, done. Free for 30 days, no credit card required.

Install in Studio Download for iOS Download for Android