Skip to content

Pipeline Plan 23

Jump to bottom
Seth Ford edited this page Feb 13, 2026 · 2 revisions

The plan file write is being blocked. Let me present the plan directly instead.

Implementation Plan: Webhook Receiver for Instant Issue Processing

Summary

Add a GitHub webhook receiver to the dashboard server so issues.labeled events trigger instant pipeline processing instead of waiting for the 30–60s poll cycle. The webhook writes to a queue file that the daemon checks each loop iteration. Polling remains as fallback.

Architecture: Dashboard (Bun/TS) receives webhook → validates HMAC-SHA256 → writes ~/.shipwright/webhook-queue.jsonl → daemon (bash) reads queue each iteration → enqueues/spawns pipeline.

Files to Modify

File Action Purpose
dashboard/server.ts Modify Add POST /api/webhook/github with HMAC-SHA256 validation, GET /api/webhook/status for delivery stats
scripts/sw-daemon.sh Modify Add webhook config to load_config() and daemon_init(), --webhook flag, daemon_check_webhook_queue(), integrate into poll loop
scripts/sw-daemon-test.sh Modify Test cases for webhook queue processing and daemon_init --webhook
dashboard/public/app.js Modify Webhook delivery status panel
dashboard/public/index.html Modify Webhook status section in layout
.claude/daemon-config.json Modify Add webhook config block

Implementation Steps

Step 1: Webhook config in daemon (sw-daemon.sh)

  • Add WEBHOOK_SECRET / WEBHOOK_ENABLED to load_config() (~line 361)
  • Add "webhook": { "enabled": false, "secret": "" } to daemon_init() generated config (~line 5155)
  • Add --webhook + --url flags: generate secret via openssl rand -hex 32, create GitHub webhook via gh api repos/{owner}/{repo}/hooks

Step 2: Webhook queue mechanism in daemon

  • Define WEBHOOK_QUEUE="$DAEMON_DIR/webhook-queue.jsonl"
  • Add daemon_check_webhook_queue(): atomically rename → read lines → enqueue issues → emit events → delete processed file
  • Call at top of daemon_poll_loop iteration (before daemon_poll_issues) for <1s pickup

Step 3: POST /api/webhook/github in dashboard server

  • HMAC-SHA256 verification via Web Crypto API
  • Load secret from daemon config
  • Validate X-Hub-Signature-256 → 401 on failure
  • Check X-GitHub-Event: issues + action === "labeled" + label matches watch_label
  • Append to webhook-queue.jsonl, log to webhook-deliveries.jsonl, emit to events.jsonl
  • Add to isPublicRoute() (uses HMAC auth, not session auth)
  • Return 202 Accepted

Step 4: GET /api/webhook/status endpoint

  • Read webhook-deliveries.jsonl, return total, last delivery, avg latency, recent 10, 24h errors

Step 5: Dashboard UI

  • Status indicator, last delivery + latency, 24h counts, recent deliveries table
  • Fetch from /api/webhook/status periodically

Step 6: Tests

  • Daemon tests: webhook queue processing, empty/missing queue, init --webhook, config loading
  • All existing tests must pass

Task Checklist

  • Task 1: Add webhook config block to load_config() and daemon_init() in sw-daemon.sh
  • Task 2: Add --webhook and --url flags to daemon init for auto-creating GitHub webhook
  • Task 3: Implement daemon_check_webhook_queue() in sw-daemon.sh
  • Task 4: Integrate daemon_check_webhook_queue at top of daemon_poll_loop
  • Task 5: Implement HMAC-SHA256 signature verification in dashboard/server.ts
  • Task 6: Add POST /api/webhook/github endpoint with validation, queue write, event emission
  • Task 7: Add GET /api/webhook/status endpoint with delivery history and stats
  • Task 8: Add webhook status panel to dashboard UI
  • Task 9: Update .claude/daemon-config.json with webhook config block
  • Task 10: Add daemon test cases for webhook queue, config loading, and init --webhook
  • Task 11: Run npm test — all tests pass
  • Task 12: Sync docs if AUTO sections stale

Testing Approach

Unit (daemon): Synthetic webhook-queue.jsonl → verify enqueue, empty/missing → no-op, init --webhook → config correct (mock gh api)

Integration (dashboard): Valid HMAC → 202 + queue written, bad sig → 401, non-labeled event → 200 no enqueue

Manual: daemon init --webhook --url http://localhost:8767 → POST test payload → issue in queue <1s → visible in dashboard

Definition of Done

  • POST /api/webhook/github accepts payloads with HMAC-SHA256 validation
  • issues.labeled events matching watch_label instantly enqueue for daemon
  • Polling continues as fallback when webhook not configured
  • shipwright daemon init --webhook --url <url> auto-creates webhook
  • Dashboard shows webhook delivery status and latency
  • All existing tests pass, new tests cover webhook features
  • Bash 3.2 compatible

Clone this wiki locally