Monitoring Your Pact Broker with Vigilmon

Your Pact Broker is the source of truth for every consumer-provider contract in your system. When it goes down, consumer tests can't publish pacts, provider verification fails, and CI pipelines block. The worst part: the failure is silent until a developer can't figure out why their tests are hanging.

By the end of this tutorial you'll have:

• HTTP monitoring on your Pact Broker's health endpoint and web UI
• Vigilmon alerts when the broker becomes unreachable
• Heartbeat monitoring for contract verification jobs
• A status page for your contract testing infrastructure

Setup takes under 20 minutes.

Step 1: Confirm your Pact Broker health endpoint

The Pact Broker (whether self-hosted or PactFlow) exposes health check endpoints out of the box.

Self-hosted Pact Broker:

# Root returns 200 with JSON on a healthy broker
curl http://localhost:9292/

# Diagnostic endpoint
curl http://localhost:9292/diagnostic/status/heartbeat

The /diagnostic/status/heartbeat endpoint is specifically designed for external health checks. It returns:

{
  "ok": true
}

with a 200 status when healthy, and a non-200 when the database connection or other internals are broken.

PactFlow (hosted):

PactFlow's API base URL returns authentication metadata. Use an authenticated request to a known endpoint, or rely on the public-facing status (PactFlow maintains a status page at their domain).

For self-hosted deployments, always use /diagnostic/status/heartbeat — it does a real database connectivity check, not just a TCP listener check.

Step 2: Deploy Pact Broker with proper supervision

If you're running the self-hosted Pact Broker, use Docker Compose with health checks:

services:
  postgres:
    image: postgres:15
    environment:
      POSTGRES_USER: pact
      POSTGRES_PASSWORD: pact
      POSTGRES_DB: pact
    volumes:
      - pact-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U pact"]
      interval: 10s
      timeout: 5s
      retries: 5

  pact-broker:
    image: pactfoundation/pact-broker:latest
    ports:
      - "9292:9292"
    environment:
      PACT_BROKER_DATABASE_URL: "postgres://pact:pact@postgres/pact"
      PACT_BROKER_LOG_LEVEL: INFO
    depends_on:
      postgres:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:9292/diagnostic/status/heartbeat"]
      interval: 30s
      timeout: 10s
      retries: 3
    restart: unless-stopped

volumes:
  pact-data:

The Docker health check gives you internal process-level monitoring. Vigilmon gives you external uptime monitoring — these complement each other.

Step 3: Set up HTTP monitoring in Vigilmon

With your Pact Broker running, connect it to Vigilmon:

1. Sign up at vigilmon.online (free, no card required)
2. Click New Monitor → HTTP
3. Enter https://pact-broker.yourdomain.com/diagnostic/status/heartbeat
4. Set check interval: 1 minute (paid) or 5 minutes (free)
5. Under Expected status code, set 200
6. Optionally under Body match, add "ok":true
7. Save

Add a second monitor for the web UI (the root URL):

https://pact-broker.yourdomain.com/   → web interface reachable

This catches the case where the health API is up but the web UI has a routing or proxy issue.

Step 4: Heartbeat monitoring for verification jobs

Contract verification is a background process — provider CI jobs run, publish verification results, and the Pact Broker records them. If those jobs stop running (broken CI, expired credentials, removed webhook), the broker stays healthy but no verification happens.

This is silent drift: your contracts are no longer being verified, but nothing is alarming.

Solve it with heartbeat monitors — one per provider-consumer pair that matters.

In your provider CI job (GitHub Actions example):

# .github/workflows/verify-contracts.yml
name: Verify Pact Contracts

on:
  push:
    branches: [main]
  schedule:
    - cron: '0 */6 * * *'  # Every 6 hours

jobs:
  verify:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: '20'

      - name: Install dependencies
        run: npm ci

      - name: Verify Pact contracts
        run: npm run test:pact
        env:
          PACT_BROKER_URL: ${{ secrets.PACT_BROKER_URL }}
          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}

      - name: Ping Vigilmon heartbeat
        if: success()
        run: curl -s "${{ secrets.VIGILMON_PACT_VERIFY_HEARTBEAT }}"

The heartbeat ping only fires on success. If the verification step fails or the workflow errors, no ping → Vigilmon alerts after one missed interval.

In Vigilmon, create a Heartbeat Monitor per provider:

1. Click New Monitor → Heartbeat
2. Name it orders-service contract verification (or similar)
3. Set expected interval to 8 hours (slightly longer than your 6-hour schedule)
4. Copy the ping URL into VIGILMON_PACT_VERIFY_HEARTBEAT

Step 5: Monitor the Pact Broker webhook dispatcher

Pact Broker webhooks trigger provider builds automatically when a consumer publishes a new pact. If webhooks stop firing, you lose the automated verification loop.

Set up a test that validates webhooks are functioning:

#!/bin/bash
# List recent webhook executions and check for failures
BROKER_URL="${PACT_BROKER_URL}"
TOKEN="${PACT_BROKER_TOKEN}"

response=$(curl -s \
  -H "Authorization: Bearer $TOKEN" \
  "${BROKER_URL}/webhooks/provider/YOUR_PROVIDER/consumer/YOUR_CONSUMER/execution")

# Check if any recent executions succeeded
echo "$response" | python3 -c "
import sys, json
data = json.load(sys.stdin)
executions = data.get('_embedded', {}).get('executions', [])
if not executions:
    print('No recent webhook executions found')
    sys.exit(1)
last = executions[0]
if last.get('success'):
    print('Last webhook execution: success')
else:
    print('Last webhook execution: FAILED')
    sys.exit(1)
"

Run this check periodically and ping a separate Vigilmon heartbeat on success.

Step 6: Slack alerts and status page

In Vigilmon, go to Notifications → New Channel → Slack and add your webhook.

When the Pact Broker goes down, your entire team's CI stops being able to verify contracts. The Slack notification removes all ambiguity:

🔴 DOWN: pact-broker.yourdomain.com/diagnostic/status/heartbeat
Status: 503 Service Unavailable
Region: EU-West
4 minutes ago

For a status page shared with your engineering org:

1. Status Pages → New Status Page
2. Add: Pact Broker health, Pact Broker UI, and each verification heartbeat monitor
3. Share the URL in your #platform or #contract-testing Slack channel

Engineers can check it when their CI starts failing before filing a support ticket.

What you've built

| What | How | |------|-----| | Broker health monitoring | Vigilmon HTTP monitor → /diagnostic/status/heartbeat | | UI availability check | Vigilmon HTTP monitor → / | | Process supervision | Docker Compose with restart policy + health checks | | Verification job monitoring | Heartbeat ping in CI on successful run | | Webhook monitoring | Periodic webhook execution check + heartbeat | | Slack alerts | Vigilmon Slack notification channel | | Platform status page | Vigilmon public status page |

Contract testing infrastructure is a shared dependency. When it's unhealthy, every team is affected. Monitor it accordingly.

Next steps

• Add a Vigilmon monitor for your Postgres instance if self-hosting — database failures show up as 500s from the broker
• Set heartbeat intervals slightly longer than your CI schedules (e.g., 2 hours for a 90-minute CI schedule) to avoid false positives without masking real missed runs
• Monitor broker response time — the Pact Broker gets slower as the number of pacts grows; a sudden slowdown can indicate a missing database index

Get started free at vigilmon.online.