2026 OpenClaw Field Practice: Bitbucket Pipelines Webhooks, Dependency Preflight & Build Summaries on a Remote Mac

Install Node 22 LTS for the UNIX account that owns the gateway. Use the official installer or npm install -g openclaw, run openclaw onboard, then openclaw doctor until PATH, listening ports, and Node version warnings are gone. Mirror the same NODE_BINARY and PATH inside a LaunchAgent plist so SSH sessions and background jobs behave identically.

Create ~/.config/openclaw/bitbucket-secret (mode 600) for the webhook secret. Store a read-only Bitbucket app password or scoped HTTP access token with Repositories: Read only—enough for git clone https://x-token-auth:<token>@bitbucket.org/…. Never place a workspace admin token on the gateway unless you are automating webhook CRUD.

In Bitbucket open Repository settings → Webhooks → Add webhook. Paste the public URL that maps to your OpenClaw route, keep SSL / TLS verification enabled, and set a long random secret—Bitbucket signs deliveries with HMAC-SHA256 and sends X-Hub-Signature: sha256=<hex> plus X-Request-UUID. You need repository admin; otherwise the UI returns permission errors that look like network faults.

Under Triggers, pick events that fire when you care about dependency policy—commonly a pipeline or build completion hook depending on your Bitbucket Cloud generation. Skip noisy triggers such as every push if you only want post-pipeline summaries. Send a test request, capture headers in nginx access_log or OpenClaw debug, and confirm your handler returns HTTP 200 within roughly ten seconds so Bitbucket stops retrying that attempt.

Verification: strip the sha256= prefix, compute HMAC_SHA256(secret, rawBody), compare with crypto.timingSafeEqual in Node or hmac.compare_digest in Python. Hash the buffer before JSON.parse. Cross-check with Atlassian’s webhook documentation if your workspace shows alternate header names behind feature flags.

// Node: rawBody must be Buffer; secret from file mode 600
// const sig = req.headers['x-hub-signature']; // 'sha256=' + hex
// const expected = crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
// crypto.timingSafeEqual(Buffer.from(sig.slice(7), 'hex'), Buffer.from(expected, 'hex'))

After authentication, parse JSON for repository.full_name, commit id, and pipeline identifiers. Export GIT_CLONE_URL with the read-only token embedded. Create a disposable directory per X-Request-UUID, git clone --depth 1 at the reported commit, then chain stack-specific dry runs: Node npm ci --dry-run or pnpm install --frozen-lockfile --prefer-offline with --dry-run where supported; Ruby bundle check plus bundle outdated --strict as a soft signal; PHP composer validate and composer install --dry-run. Exit non-zero only for policy breaches you want highlighted; capture the last eighty lines of stdout/stderr into the summary payload.

Keep the synchronous slice under the webhook budget: verify signature, optionally enqueue a LaunchAgent job or OpenClaw skill with the UUID, return { "accepted": true, "requestUuid": "…" } immediately. Run the heavy chain in the worker. The same orchestration pattern appears in the Jenkins generic webhook preflight playbook—swap payload fields only.

#!/usr/bin/env bash
set -euo pipefail
# bb-preflight.sh <clone-url> <commit>
WORKDIR="$(mktemp -d /tmp/bb-pf-XXXXXX)"
git clone --depth 48 "$1" "$WORKDIR/repo"
cd "$WORKDIR/repo" && git checkout --detach "$2"
npm ci --dry-run 2>&1 | tail -n 80

Tail log show --predicate 'process == "node"' --last 30m when launchd stderr is empty; often the plist WorkingDirectory or token env var is missing compared to your interactive SSH test.

When preflight finishes, POST a compact JSON document to your chat webhook or internal API: include repository, commit, pipelineUuid, preflightExitCode, truncated log excerpt, and a deep link to the Bitbucket pipeline run. Use three attempts with sleeps of 2, 4, and 8 seconds and an HTTP client timeout near 25 seconds per attempt so transient egress blips do not lose the summary.

If the outbound endpoint requires its own bearer token, store it beside the Bitbucket read token with the same mode 600 and separate rotation policy. Structured fields make it easy to alert only when preflightExitCode != 0 while still archiving every run for audits.

Reference numbers you can quote: ten-second synchronous budget for the inbound hook; three summary retries; twenty four-hour dedupe window for UUIDs; twenty five-second per-attempt outbound timeout.

1. Doctor-clean gateway user with pinned Node and plist env.
2. TLS → loopback; raw POST bytes preserved for HMAC.
3. Bitbucket secret on disk; repository read token scoped.
4. Preflight in worker; fast 200 JSON acknowledgment.
5. Summary POST 2/4/8s retries; UUID dedupe store warm.

Rent a remote Mac for always-on webhooks: laptops sleep; data-center Mac Minis do not. Start from Home, compare plans on Pricing, provision via Purchase, then use Help for SSH. More automation articles live on the Technical Blog.