bmad-template/.agents/skills/bmad-testarch-test-review/resources/knowledge/pact-broker-webhooks.md

# Pact Broker Webhooks (PactFlow → GitHub)

## Principle

Configure PactFlow webhooks to trigger provider verification in GitHub Actions via a dedicated GitHub machine user, a long-lived classic Personal Access Token (PAT), and a PactFlow-stored secret. Monitor for silent webhook failures so an expired/revoked token does not quietly block deployments for days.

## Rationale

### Why webhooks matter

- PactFlow's `contract_requiring_verification_published` webhook is the mechanism that notifies a provider repo (via `repository_dispatch`) that a consumer has published a contract needing verification.
- Without a working webhook, `can-i-deploy` in the consumer CI **times out** (900s) and eventually fails with `There is no verified pact between <consumer-version> and the version of <provider> currently in <env>` — even though nothing is wrong in either codebase.
- Webhook failures are **silent by default**: PactFlow keeps emitting requests, GitHub keeps returning `401 Unauthorized`, but nothing alerts the team until a PR is blocked.

### Why a dedicated GitHub machine user (not a personal PAT)

- Personal PATs die when the person leaves the company, rotates laptops, or revokes credentials during a security review. The contract test pipeline then breaks for reasons unrelated to any code change.
- A dedicated machine user (e.g., `pactflow-<org>`) is owned by the org, has only the repos it needs, and the PAT lifecycle is controlled by the security/platform team.
- GitHub **billing does not count** machine users added as outside collaborators to the specific repos they need — confirm with the org owner before assuming it's free.

### Why classic PAT with `repo` scope and no expiration

- PactFlow's webhook calls the GitHub REST API's `repository_dispatch` endpoint. This endpoint requires the **`repo` scope** on a classic PAT (fine-grained PATs work for many flows but have edge cases with `repository_dispatch` that are not universally supported at time of writing — verify with current GitHub docs).
- Classic PATs support "No expiration" — required to avoid the silent-failure trap every 90 days. GitHub warns against this for human users; for a locked-down machine-user PAT stored in PactFlow's secret vault, the security trade-off is documented and accepted.
- The alternative — rotating a PAT every 30/60/90 days — requires tooling and coordination most teams don't yet have. Long-lived + monitored + machine-user-owned is the pragmatic default.

## Pattern Examples

### Example 1: Webhook URL, Headers, and Body

```json
{
  "description": "Notify <provider-repo> when a consumer contract requires verification",
  "events": [{ "name": "contract_requiring_verification_published" }],
  "provider": { "name": "<provider-pacticipant-name>" },
  "request": {
    "method": "POST",
    "url": "https://api.github.com/repos/<org>/<provider-repo>/dispatches",
    "headers": {
      "Accept": "application/vnd.github+json",
      "Authorization": "Bearer ${user.githubToken}",
      "Content-Type": "application/json",
      "User-Agent": "PactFlow",
      "X-GitHub-Api-Version": "2022-11-28"
    },
    "body": {
      "event_type": "contract_requiring_verification_published",
      "client_payload": {
        "pact_url": "${pactbroker.pactUrl}",
        "sha": "${pactbroker.providerVersionNumber}",
        "branch": "${pactbroker.providerVersionBranch}",
        "consumer_name": "${pactbroker.consumerName}",
        "consumer_version_number": "${pactbroker.consumerVersionNumber}",
        "consumer_version_tags": "${pactbroker.consumerVersionTags}",
        "consumer_version_branch": "${pactbroker.consumerVersionBranch}"
      }
    }
  }
}
```

**Key Points**:

- `${user.githubToken}` references a PactFlow **secret** stored in `Settings → Secrets` (web UI: `/settings/secrets`). The secret holds the classic PAT — never inline the token in the webhook body.
- `${pactbroker.*}` are PactFlow-injected template variables; the provider workflow reads them from `github.event.client_payload`.
- Use the `contract_requiring_verification_published` event (not `contract_published`) — the former fires only when a new pact _content_ change needs verification; the latter fires on every publish, including no-op republishes.

### Example 2: Provider GitHub Actions Workflow (Triggered by Webhook)

```yaml
# .github/workflows/contract-test-provider.yml
name: contract-test-provider

on:
  repository_dispatch:
    types: [contract_requiring_verification_published]
  push:
    branches: [main]

jobs:
  verify:
    runs-on: ubuntu-latest
    env:
      PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
      PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
      # Pulled from webhook client_payload when triggered by PactFlow:
      PACT_PAYLOAD_URL: ${{ github.event.client_payload.pact_url }}
      GITHUB_SHA: ${{ github.event.client_payload.sha || github.sha }}
      GITHUB_BRANCH: ${{ github.event.client_payload.branch || github.head_ref || github.ref_name }}
    steps:
      - uses: actions/checkout@v4
        with:
          # Check out the provider version known to the broker — this is the provider SHA PactFlow wants verified.
          ref: ${{ github.event.client_payload.sha || github.sha }}
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm ci
      - name: Run provider verification
        run: npm run test:pact:provider
      - name: Can I deploy provider?
        if: github.event_name == 'push'
        run: npm run can:i:deploy:provider
```

**Key Points**:

- `repository_dispatch` is the event type emitted by GitHub when the webhook's REST call hits `/repos/<org>/<repo>/dispatches`.
- The `types` filter must match the webhook's `event_type` (`contract_requiring_verification_published` here).
- Checking out the provider version known to the broker (`providerVersionNumber`) ensures verification runs against the exact provider commit PactFlow registered — not whatever is on main.
- `PACT_PAYLOAD_URL` makes `buildVerifierOptions` verify only the triggering pact (see `pactjs-utils-provider-verifier.md` Example 1).

### Example 3: Secret Rotation Runbook

**Trigger**: `can-i-deploy` in a consumer repo times out with `There is no verified pact between <consumer-version> and the version of <provider> currently in <env>` — AND the provider's `contract-test-provider` workflow shows no recent `repository_dispatch` runs.

**Diagnosis**:

1. In PactFlow UI: `Settings → Webhooks → <webhook-id> → Test`. A `401 Unauthorized` from GitHub confirms the token is dead.
2. In PactFlow UI: the webhook's "Last executed at" is hours/days stale while consumer pacts are actively being published.

**Rotation**:

1. Log in to GitHub as the dedicated machine user (e.g., `pactflow-<org>`). **Do not use a personal account** — the whole point of the machine user is that the token outlives any individual.
2. `Settings → Developer settings → Personal access tokens → Tokens (classic) → Generate new token (classic)`.
3. Configure the token:
   - Name: `pactflow-webhook-<yyyy-mm-dd>`
   - Expiration: **No expiration** (accepted trade-off for a locked-down machine-user token stored in PactFlow's secret vault)
   - Scopes: **`repo`** (full repo scope is required by `repository_dispatch`; `public_repo` alone is insufficient for private repos)
4. Copy the new token value (shown only once).
5. In PactFlow UI: `Settings → Secrets → <secret-name>` (e.g., `githubToken`). Paste the new token into the **value** field and save. The webhook does not need to be edited — it references the secret by name via `${user.<secret-name>}`.
6. Re-test the webhook: `Settings → Webhooks → <webhook-id> → Test`. Expect `HTTP/1.1 204 No Content` (GitHub's success response for `repository_dispatch`).
7. In the provider repo: watch `Actions → contract-test-provider` for the newly dispatched run. Re-run the original consumer CI to confirm `can-i-deploy` now passes.
8. Revoke the old token: in the machine user's GitHub settings, delete the previous `pactflow-webhook-*` token so a leaked copy can't be reused.

**Why no expiration**: A token with a 90-day expiry rotates 4× per year. Each rotation is a silent-failure window if the runbook isn't executed proactively. With monitoring (Example 4) + a locked-down machine-user-owned PAT that is only stored in PactFlow, long-lived is safer than short-lived-but-forgotten.

### Example 4: Staleness Monitoring (Detect Silent Webhook Failures)

**Goal**: Alert the team if verification results haven't been published for a pacticipant pair in the last N hours, so an expired PAT or network issue doesn't silently block `can-i-deploy` for days.

Pick one of these (in increasing order of investment):

**Option A — Daily sanity CI job (cheapest)**:

```yaml
# .github/workflows/pact-staleness-check.yml
name: pact-staleness-check
on:
  schedule:
    - cron: '0 9 * * 1-5' # weekdays 09:00 UTC
  workflow_dispatch:
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - name: Fail if latest verification for <pair> is older than 24h
        env:
          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
        run: |
          # Query broker matrix for newest verification timestamp for consumer/provider pair.
          # Exit 1 if > 24h old; team gets an email on the failed scheduled run.
          ./scripts/assert-recent-verification.sh <consumer> <provider> 86400
```

**Option B — PactFlow metrics endpoint**: Use the SmartBear MCP `get_metrics` / `get_team_metrics` tool (see `pact-mcp.md`) to surface verification freshness in a dashboard or Slack digest.

**Option C — Webhook delivery log**: PactFlow logs every webhook execution. Ship those logs to your SIEM / observability stack and alert on sustained 4xx responses from `api.github.com`.

**Key Points**:

- The point is not "which option you pick" — it's that **you pick at least one**. Without monitoring, the first time you learn the webhook is dead is when a release is blocked.
- Alert threshold should match your consumer-publish cadence: if consumers publish daily, alert after 24–48h of silence; if hourly, after 3–6h.
- Keep the alert noise-free: page only on sustained staleness, not a single missed run.

## Key Points

- **Dedicated machine user owns the PAT** — never a personal PAT. Name it `pactflow-<org>` or similar; give it outside-collaborator access only to the specific provider repos.
- **Classic PAT, `repo` scope, no expiration** — required for `repository_dispatch`. The "no expiration" trade-off is accepted in exchange for machine-user ownership + PactFlow-secret storage + staleness monitoring.
- **Store the PAT as a PactFlow secret** at `/settings/secrets`, reference it from the webhook via `${user.<secret-name>}`. Never inline the token.
- **Monitor for silence** — at minimum, a daily scheduled CI job that asserts a recent verification timestamp exists for each critical consumer/provider pair.
- **Rotation is a runbook, not an emergency** — document it (see Example 3), keep it in the repo, and do a practice rotation once a year so it stays fresh.
- **Symptom to remember**: "consumer `can-i-deploy` timeout after 900s with `There is no verified pact...`" + "provider's `contract-test-provider` workflow has no recent runs" = expired/revoked PAT. Start with Example 3.

## Related Fragments

- `pactjs-utils-provider-verifier.md` — how `PACT_PAYLOAD_URL` from the webhook's `client_payload.pact_url` is consumed by `buildVerifierOptions`
- `pact-consumer-framework-setup.md` — consumer CI flow that issues `can-i-deploy` and silently times out when the webhook is dead
- `pact-mcp.md` — SmartBear MCP tools (`Matrix`, `Metrics - All`) useful for staleness monitoring dashboards
- `contract-testing.md` — foundational CDC patterns and resilience coverage

## Anti-Patterns

### Wrong: Using a human's personal PAT

```
# ❌ PactFlow secret githubToken stores the lead engineer's personal classic PAT
# When they leave / rotate / revoke → all provider verifications stop silently
```

### Right: Dedicated machine user owns the PAT

```
# ✅ Machine user `pactflow-<org>` generates the PAT; secret is owned by the org
# PAT lifecycle is decoupled from any individual's employment or laptop state
```

### Wrong: No staleness monitoring

```
# ❌ No scheduled check for verification recency
# First signal that the webhook is dead: a blocked release PR, several days later
```

### Right: Daily scheduled sanity check

```
# ✅ Scheduled workflow fails if latest verification > 24h old
# Team gets email alert on failed scheduled run → rotate PAT before anyone is blocked
```

### Wrong: Short-expiration PAT with no rotation tooling

```
# ❌ 90-day expiry PAT, no calendar reminder, no runbook
# Breaks every 90 days for a day or two until someone notices
```

### Right: No-expiration PAT on machine user + monitoring + documented runbook

```
# ✅ Long-lived PAT, scoped narrowly, stored in PactFlow, monitored for staleness
# Rotation is intentional (security review, suspected leak) not calendar-driven
```

_Source: PactFlow webhook documentation, GitHub `repository_dispatch` REST API, seon-mcp-server / seon-admin-panel production incident April 2026_