docs: Webhook setup guide for GitHub-to-swarm notifications

[nexus-marbell]

Summary

Create comprehensive documentation for the GitHub Webhook to Swarm Notification Bridge, covering setup, configuration, and security best practices.

RFC: #177 (GitHub Webhook to Swarm Notification Bridge)

Scope

New Documentation File

• docs/GITHUB-WEBHOOKS.md -- standalone guide for the webhook bridge

Content Sections

1. Overview

• What the webhook bridge does and why it exists
• The "Dominik use case": surfacing external contributor activity
• Architecture diagram showing GitHub -> webhook endpoint -> swarm message flow

2. GitHub Webhook Configuration

• Step-by-step: Settings -> Webhooks -> Add webhook in each GitHub repo
• Payload URL: https://<your-endpoint>/api/github-webhook
• Content type: application/json
• Secret: how to generate a secure secret (openssl rand -hex 32)
• Which events to subscribe to (issues, issue_comment, pull_request, pull_request_review)
• Screenshots or descriptions of the GitHub UI steps

3. Environment Variable Reference

• GITHUB_WEBHOOK_ENABLED -- purpose, type, default
• GITHUB_WEBHOOK_SECRET -- purpose, how to set securely
• GITHUB_WEBHOOK_ROUTING -- full format specification with examples
• GITHUB_WEBHOOK_BATCH_THRESHOLD -- purpose, default
• GITHUB_WEBHOOK_BATCH_WINDOW -- purpose, default
• GITHUB_WEBHOOK_RATE_LIMIT -- purpose, default

4. Routing Configuration Examples

• Single repo, single agent
• Single repo, multiple agents
• Multiple repos, single agent
• Wildcard patterns
• Full multi-agent swarm configuration example

5. Per-Agent Setup Instructions

• Each agent adds their repos to their own GITHUB_WEBHOOK_ROUTING
• Each agent generates and manages their own GITHUB_WEBHOOK_SECRET
• How to configure the webhook on the GitHub repo side to point at the agent's endpoint
• Testing with gh webhook or curl to verify setup

6. Security Best Practices

• Always use HMAC-SHA256 verification (never disable)
• How to rotate webhook secrets (update env var + GitHub webhook config)
• Use HTTPS endpoints only
• Rate limiting protects against abuse
• Monitoring webhook delivery failures in GitHub UI

7. Troubleshooting

• Common issues: 403 (bad secret), 404 (feature disabled), no messages (routing misconfigured)
• How to check webhook delivery logs in GitHub
• How to verify routing config is correct

Updates to Existing Docs

• docs/ENVIRONMENT.md -- add all GITHUB_WEBHOOK_* env vars to the centralized reference
• .env.example -- add GITHUB_WEBHOOK_* vars with comments
• docs/API.md -- add /api/github-webhook endpoint reference

Acceptance Criteria

• docs/GITHUB-WEBHOOKS.md exists with all sections listed above
• Step-by-step GitHub webhook configuration instructions are clear and complete
• All GITHUB_WEBHOOK_* env vars are documented with types, defaults, and examples
• Routing config format is fully specified with multiple examples
• Per-agent setup instructions explain the multi-agent model
• Security best practices section covers secret rotation and HTTPS
• Troubleshooting section covers common failure modes
• docs/ENVIRONMENT.md updated with new env vars
• .env.example updated with new env vars
• docs/API.md updated with webhook endpoint reference

Dependencies

Depends on #178 (endpoint), #179 (routing config), #180 (event formatting), #181 (batching/rate limiting).
This issue should be completed last, after all implementation issues are done, to document the final behavior accurately.