feat: initial GitHub webhook receiver implementation

- FastAPI service for receiving GitHub webhooks
- HMAC-SHA256 signature verification
- Event handlers for push, PR, issues, comments, workflows, deployments
- Structured logging with context
- Health check endpoint
- PDM dependency management
- Pytest test suite
- Systemd service configuration
- GitHub Actions deployment workflow

Multi-repo coordination foundation - handlers are stubs for now.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <[email protected]>

Author: westover

.env.example

@@ -0,0 +1,13 @@
+# GitHub Webhook Receiver Configuration
+
+# Application
+APP_ENV=production
+APP_PORT=9000
+APP_HOST=0.0.0.0
+
+# GitHub Webhook Secret (from GitHub App)
+GITHUB_WEBHOOK_SECRET=your-webhook-secret-here
+
+# Logging
+LOG_LEVEL=INFO
+LOG_FORMAT=json

.github/workflows/deploy.yml

@@ -0,0 +1,30 @@
+name: Deploy Webhook Receiver
+
+on:
+  push:
+    branches:
+      - main
+  workflow_dispatch:
+
+jobs:
+  deploy:
+    runs-on: [self-hosted, app-server]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Install dependencies
+        run: pdm install --prod
+
+      - name: Run tests
+        run: pdm run pytest
+
+      - name: Deploy service
+        run: |
+          sudo systemctl restart github-webhook-receiver
+          sleep 2
+          curl -f http://localhost:9000/health || exit 1
+
+      - name: Deployment successful
+        run: echo "✅ Webhook receiver deployed successfully"

.gitignore

@@ -0,0 +1,57 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PDM
+.pdm.toml
+.pdm-python
+__pypackages__/
+
+# Virtual environments
+.venv/
+venv/
+ENV/
+env/
+
+# Environment variables
+.env
+.env.local
+
+# IDE
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+
+# Logs
+*.log
+
+# OS
+.DS_Store
+Thumbs.db

README.md

@@ -0,0 +1,136 @@
+# GitHub Webhook Receiver
+
+Multi-repo coordination and automation webhook receiver for the neherdata organization.
+
+## Overview
+
+Receives GitHub webhooks from the `Neherdata-deploy-bot` GitHub App to enable:
+- Multi-repo deployment coordination
+- Claude automation triggers
+- Cross-repo workflow orchestration
+- Centralized event logging and monitoring
+
+## Features
+
+- **Webhook Verification**: HMAC-SHA256 signature verification
+- **Event Processing**: Handles push, PR, issues, comments, workflows, deployments
+- **Structured Logging**: JSON logs with context for debugging
+- **Health Monitoring**: Health check endpoint for monitoring
+- **Extensible**: Easy to add new event handlers
+
+## Setup
+
+### Prerequisites
+
+- Python 3.11+
+- PDM (Python Dependency Manager)
+- Cloudflare tunnel configured
+
+### Installation
+
+```bash
+# Clone repository
+git clone https://github.com/neherdata/github-webhook-receiver.git
+cd github-webhook-receiver
+
+# Install dependencies
+pdm install --prod
+
+# Configure environment
+cp .env.example .env
+# Edit .env with your configuration
+```
+
+### Configuration
+
+```bash
+# .env
+GITHUB_WEBHOOK_SECRET=your-webhook-secret-from-github-app
+APP_PORT=9000
+APP_HOST=0.0.0.0
+LOG_LEVEL=INFO
+```
+
+### Running
+
+```bash
+# Development
+pdm run uvicorn app.main:app --reload --port 9000
+
+# Production (via systemd)
+sudo systemctl start github-webhook-receiver
+```
+
+## Deployment
+
+Deployed to westoverxyz via Ansible:
+
+```bash
+cd /path/to/nds_server/ansible
+ansible-playbook playbooks/deploy-webhook-receiver.yml
+```
+
+Service runs on port 9000, exposed via Cloudflare tunnel at:
+- `https://github-webhooks.westover.services/webhooks/github`
+- `https://github-callback.westover.services` (OAuth callbacks)
+
+## Event Handlers
+
+### Implemented
+
+- ✅ **push**: Deployment coordination (TODO: implement logic)
+- ✅ **pull_request**: PR coordination (TODO: implement logic)
+- ✅ **issues**: Claude automation trigger (TODO: implement logic)
+- ✅ **issue_comment**: Comment-triggered actions (TODO: implement logic)
+- ✅ **workflow_run**: Workflow monitoring (TODO: implement logic)
+- ✅ **deployment**: Deployment tracking (TODO: implement logic)
+
+### Planned
+
+- Cross-repo dependency updates
+- Automated changelog generation
+- Deployment status aggregation
+- Claude task coordination
+
+## Testing
+
+```bash
+# Run tests
+pdm run pytest
+
+# Test webhook locally
+curl -X POST http://localhost:9000/webhooks/github \
+  -H "X-Hub-Signature-256: sha256=..." \
+  -H "X-GitHub-Event: ping" \
+  -H "X-GitHub-Delivery: abc123" \
+  -d '{"zen": "testing"}'
+```
+
+## Security
+
+- Webhook signatures verified using HMAC-SHA256
+- Secret stored in environment variables (not in code)
+- Rate limiting via Cloudflare
+- Systemd service runs as non-root user
+
+## Monitoring
+
+- Health endpoint: `/health`
+- Structured logs: `sudo journalctl -u github-webhook-receiver -f`
+- Cloudflare Analytics dashboard
+
+## Architecture
+
+```
+GitHub Event → GitHub App → Cloudflare Tunnel → FastAPI Receiver
+                                                       ↓
+                                                Event Handlers
+                                                       ↓
+                                          [Coordination Logic]
+                                                       ↓
+                                    Trigger Actions (deployments, etc.)
+```
+
+## License
+
+MIT

app/__init__.py

@@ -0,0 +1,3 @@
+"""GitHub Webhook Receiver"""
+
+__version__ = "1.0.0"