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

# 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

# .env
GITHUB_WEBHOOK_SECRET=your-webhook-secret-from-github-app
APP_PORT=9000
APP_HOST=0.0.0.0
LOG_LEVEL=INFO

Running

# 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:

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

# 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