How to Send a Bitbucket Pipelines Success Alert to Your Team's Phones

To send a Bitbucket Pipelines success alert to a small team's phones, add a success-only PingRoom request to the after-script of the final step that matters. Store the full incoming-webhook URL as a secured repository variable, and use Bitbucket's pipeline UUID as both the idempotency key and correlation ID.

This is a direct webhook recipe, not a native Bitbucket integration. The Room owner needs PingRoom Pro, the final build image needs curl, and a repository admin should configure the secured variable.

Decide whether you need a separate phone alert

Bitbucket's pipeline history remains the source of truth. It records whether a pipeline is successful, failed, paused, stopped, or in an error state. Start with Bitbucket's own view and your team's existing collaboration notifications when those already reach the right people.

The recipe below reports one narrow fact: the selected final step completed successfully on one chosen branch. It does not prove that a deployment is healthy, that every downstream system is available, or that every phone displayed a notification.

Create the destination Room and secure the URL

Create or choose a private Room for the stable group that needs the completion signal. Open Settings → Connections → From another app, add a webhook named Bitbucket pipeline, choose Custom message, and copy the complete URL.

The incoming-webhook setup guide covers the Room-side steps. The webhook reference documents current fields, limits, idempotency behavior, and errors.

In Bitbucket, add the URL as a repository variable named PINGROOM_WEBHOOK_URL and mark it Secured. Add PINGROOM_NOTIFY_BRANCH as a normal variable if the target should be something other than main.

A secured variable masks matching values in logs, but the URL is still a credential. Do not print it, transform it for debugging, commit it, or copy it into screenshots. If it leaks, regenerate the PingRoom webhook secret and replace the variable.

Add the success-only helper

Save this as ci/notify-pingroom-success.sh in the repository:

#!/bin/sh
set -eu

if [ "${BITBUCKET_EXIT_CODE:-1}" != "0" ]; then
  echo "PingRoom: skipped because the selected final step did not succeed."
  exit 0
fi

notify_branch=${PINGROOM_NOTIFY_BRANCH:-main}
if [ "${BITBUCKET_BRANCH:-}" != "$notify_branch" ]; then
  echo "PingRoom: skipped branch ${BITBUCKET_BRANCH:-unknown}."
  exit 0
fi

: "${PINGROOM_WEBHOOK_URL:?Set a secured PINGROOM_WEBHOOK_URL repository variable}"
: "${BITBUCKET_PIPELINE_UUID:?Bitbucket did not provide BITBUCKET_PIPELINE_UUID}"

pipeline_uuid=${BITBUCKET_PIPELINE_UUID#\{}
pipeline_uuid=${pipeline_uuid%\}}
case "$pipeline_uuid" in
  "" | *[!A-Za-z0-9-]*)
    echo "PingRoom: invalid pipeline UUID." >&2
    exit 1
    ;;
esac

event_key="bitbucket-pipeline-$pipeline_uuid"
payload=$(printf \
  '{"title":"Selected pipeline succeeded","message":"The selected final step completed successfully. Verify the result in Bitbucket before acting.","correlation_id":"%s"}' \
  "$event_key")

if ! curl --fail-with-body --silent --show-error --max-time 8 \
  --request POST "$PINGROOM_WEBHOOK_URL" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --header "Idempotency-Key: $event_key" \
  --data "$payload" \
  >/dev/null; then
  echo "PingRoom: the completion alert was not accepted; check this step log." >&2
  exit 1
fi

echo "PingRoom: completion alert accepted."

The request deliberately excludes repository, branch, commit, author, URL, and log data. The fixed title and message reveal only that a selected pipeline reached its chosen final step. If even that is too specific for a lock screen, use a more neutral saved webhook message.

BITBUCKET_PIPELINE_UUID can include braces. The helper removes only the outside braces, validates the remaining UUID characters, and prefixes the result before using it as a PingRoom idempotency key. An exact retry therefore resolves to the same event identity instead of creating a second Ping.

Attach it to the final step that matters

Add the helper to the after-script of the real final step whose success should notify the Room. This illustrative pipeline uses one sequential step; adapt the script commands to your repository.

pipelines:
  branches:
    main:
      - step:
          name: Build, test, and deploy
          script:
            - ./ci/build.sh
            - ./ci/test.sh
            - ./ci/deploy.sh
          after-script:
            - sh ci/notify-pingroom-success.sh

Bitbucket runs after-script after the step and exposes its result as BITBUCKET_EXIT_CODE. The helper exits quietly for a failed step or the wrong branch. It sends only when both gates match.

An after-script failure does not change Bitbucket's reported step result. A rejected PingRoom request is written clearly to the step log, but it does not turn a successful build into a failed one. If notification delivery must block a release, use a durable final notification step or a relay with its own retries and monitoring instead of this lightweight pattern.

At the editorial workbench, Pingo—PingRoom's fictional CMO—watches the team close the build folio before moving one capsule to the alert tray. His half-lidded review is useful here: the phone gets the completion fact, while the build details stay in Bitbucket. The human team still owns the setup and every claim.

Test the boundary before using it on a real branch

Run a harmless pipeline and check these cases:

1. A successful final step on the selected branch produces one Room Ping.
2. A failed final step produces no Ping.
3. A success on another branch produces no Ping.
4. Replaying the same pipeline UUID and body returns the original accepted result rather than creating another Ping.
5. A rejected request is visible in the step log without changing Bitbucket's pipeline status.

Then lock a test phone and read the alert as if you knew nothing about the pipeline. The title should be useful without leaking a project name, branch, commit, customer, or environment.

Our production check exercised the exact helper against a local stateful mock for all five cases. It did not use a live Bitbucket repository, PingRoom Room, phone, or network request, so your first harmless real pipeline is still part of setup.

For a broader decision framework, read how to design CI/CD deployment notifications. Keep build history, logs, approvals, rollback controls, and incident escalation in their existing systems; use the Room as a bounded attention path.

Send the first completion Ping

Open PingRoom Rooms, create the private destination Room, add the incoming webhook, and run one harmless successful pipeline on the selected branch. Confirm the Bitbucket step log, the single Room event, and what the test phone actually displays before connecting a production release.