feat: Universal Webhook Router

[research-developer]

Overview

Implement a universal webhook router that can automatically detect and route webhooks from multiple platforms to appropriate handlers.

Problem

When running a single webhook endpoint, we need to:

1. Identify which platform sent the webhook
2. Verify the signature using the correct method
3. Parse the payload into typed models
4. Route to appropriate handlers

Solution ✅ Implemented

Created pr_agent/webhooks/ module with:

Detection (router.py)

• Header-based detection (platform-specific headers)
• Payload structure analysis
• User-Agent inspection
• Confidence scoring for accuracy

Models (models.py)

• WebhookSource enum for all platforms
• WebhookHeaders normalized header container
• WebhookPayload universal payload wrapper
• Platform-specific WebhookEvent subclasses

Supported Platforms

Platform	Header Detection	Payload Detection	Signature Verification
GitHub	X-GitHub-Event, X-Hub-Signature-256	repository, sender	HMAC SHA256
Vercel	x-vercel-signature	type, deploymentId	HMAC SHA1
Linear	Linear-Signature, Linear-Event	type, action, data	HMAC SHA256
Slack	X-Slack-Signature	team_id, api_app_id	HMAC SHA256
Discord	X-Signature-Ed25519	type (int), application_id	Ed25519
Gmail	-	Pub/Sub structure	-
Railway	User-Agent	deployment, service	-

Usage

from pr_agent.webhooks import WebhookRouter, WebhookSource

router = WebhookRouter()
router.set_secret(WebhookSource.GITHUB, "github_secret")

@router.on(WebhookSource.GITHUB)
async def handle_github(event):
    print(f"GitHub: {event.event_type} on {event.repository}")

# In webhook endpoint:
event = await router.handle_webhook(headers, body, raw_body)

Files

• pr_agent/webhooks/__init__.py
• pr_agent/webhooks/models.py
• pr_agent/webhooks/router.py

Remaining Tasks

• Add FastAPI endpoint example
• Add tests for each platform detection
• Add confidence threshold configuration
• Add Notion webhook support