Files
stack/docs/scratchpads/157-webhook-receiver.md
Jason Woltje a5416e4a66 fix(#180): Update pnpm to 10.27.0 in Dockerfiles
Updated pnpm version from 10.19.0 to 10.27.0 to fix HIGH severity
vulnerabilities (CVE-2025-69262, CVE-2025-69263, CVE-2025-6926).

Changes:
- apps/api/Dockerfile: line 8
- apps/web/Dockerfile: lines 8 and 81

Fixes #180
2026-02-01 20:52:43 -06:00

1.8 KiB

Issue #157: Set up webhook receiver endpoint

Objective

Implement FastAPI webhook receiver that handles Gitea issue assignment events with HMAC SHA256 signature verification.

Approach

  1. Create new Python service: apps/coordinator/ (FastAPI app)
  2. Structure:
    • src/main.py - FastAPI application entry point
    • src/webhook.py - Webhook endpoint handlers
    • src/security.py - HMAC signature verification
    • src/config.py - Configuration management
    • tests/ - Unit and integration tests
  3. Follow TDD: Write tests first, then implementation
  4. Add Docker support with health checks
  5. Update docker-compose for coordinator service

Progress

  • Create directory structure
  • Write tests for HMAC signature verification (RED)
  • Implement signature verification (GREEN)
  • Write tests for webhook endpoint (RED)
  • Implement webhook endpoint (GREEN)
  • Write tests for event routing (RED)
  • Implement event routing (GREEN)
  • Add health check endpoint
  • Create Dockerfile
  • Update docker-compose.yml
  • Run quality gates (build, lint, test, coverage)
  • Update .env.example with webhook secret
  • Commit implementation (commit: e23c09f)
  • Update issue status

Testing

  • Unit tests for security.verify_signature()
  • Unit tests for each event handler (assigned, unassigned, closed)
  • Integration test with mock Gitea webhook payload
  • Security test: Invalid signature returns 401
  • Health check test

Notes

  • Python service alongside NestJS apps (polyglot monorepo)
  • Use pytest for testing framework
  • Use pydantic for request validation
  • Minimum 85% coverage required
  • Need to add webhook secret to .env.example

Token Tracking

  • Estimated: 52,000 tokens
  • Actual: ~58,000 tokens (112% of estimate)
  • Overhead mainly from venv setup and linting/type-check fixes