Webhook Ingestion & Event Routing
Relevant source files
The following files were used as context for generating this wiki page:
Webhook Ingestion and Event Routing form the entry point for the AI Code Reviewer system. This module is responsible for receiving payloads from GitHub, verifying their authenticity, persisting the delivery for audit and deduplication, and routing specific events to the appropriate background workers. The architecture decouples the immediate HTTP response from the long-running processing tasks, ensuring high availability and reliability.
Sources: README.md:12-25, apps/web/app/api/webhooks/github/route.ts:13-22
Architecture Overview
The system utilizes a split-process architecture where the web server (apps/web) handles synchronous HTTP intake and the worker (apps/worker) handles asynchronous processing via a PostgreSQL-backed job queue (pg-boss).
The Two-Stage Pipeline
- Intake (Web Process): The
/api/webhooks/githubroute validates the HMAC signature, stores the raw payload in theWebhookDeliverytable, and enqueues awebhook.processjob. - Routing (Worker Process): The worker picks up the job, parses the event type, and triggers specific handlers (e.g., creating a review record or updating repository metadata).
Sources: README.md:58-69, apps/web/app/api/webhooks/github/route.ts:88-102
The following sequence diagram illustrates the lifecycle of a GitHub webhook delivery:
Webhook Intake & Security
The intake route is designed to be highly secure and performant, adhering to GitHub's requirement for fast responses.
Security and Validation
- HMAC Verification: The system computes an HMAC-SHA256 signature using the
GITHUB_WEBHOOK_SECRETand compares it to thex-hub-signature-256header using a timing-safe comparison. - Payload Capping: Content is capped at 25 MB to prevent memory exhaustion from massive push events.
- Deduplication: Every delivery is identified by a unique
x-github-deliveryheader. This is stored in the database with a unique constraint. If a delivery is retried by GitHub, the system detects the existingprocessedAttimestamp and returns immediately.
Sources: apps/web/app/api/webhooks/github/route.ts:40-61, apps/web/app/api/webhooks/github/route.ts:88-102
Webhook Delivery Schema
| Field | Type | Description |
|---|---|---|
deliveryId | String | Unique ID provided by GitHub (e.g., x-github-delivery). |
event | String | The type of event (e.g., pull_request, push). |
payload | Json | The full raw body sent by GitHub. |
processedAt | DateTime? | Timestamp marking when the worker completed routing. |
Sources: packages/db/prisma/schema.prisma:358-368
Event Routing Logic
Once the worker receives a webhook.process job, the handleWebhookDelivery function routes the event to specialized handlers based on the event and action fields.
Primary Event Handlers
1. Pull Request Events
This handler monitors opened, synchronize, and reopened actions. It ensures the repository is enabled in the system and that the PR is not a draft. If valid, it creates a PENDING AiReview record and enqueues the actual LLM review job.
Sources: packages/ingestion/src/process-webhook.ts:65-115
2. Push Events
Triggered on code pushes to enabled repositories. It identifies changed or added file paths across all commits in the push and enqueues index.file jobs for incremental RAG indexing.
Sources: packages/ingestion/src/process-webhook.ts:245-283
3. Installation Events
Handles the lifecycle of the GitHub App across organizations.
installation: Manages thesuspendedstate of an entire installation.installation_repositories: Synchronizes the list of repositories the app has access to. When a repository is removed from the app's scope, it is automatically marked asenabled = falsein the database.
Sources: packages/ingestion/src/process-webhook.ts:168-232
4. Developer Comment Events
Listens to pull_request_review_comment and issue_comment. These events are routed to ProcessDeveloperComment jobs to support "Review Memory" (Layer 2) and interactive Q&A with the AI.
Sources: packages/ingestion/src/process-webhook.ts:303-340, packages/ingestion/src/process-webhook.ts:358-392
Data Persistence & Idempotency
The ingestion system ensures idempotency to handle GitHub's potential redeliveries and network failures.
- Atomic Review Creation: Before enqueuing a
review.prjob, the system checks for an existingAiReviewrecord matching therepositoryId,pullRequestNumber, andcommitSha. - Processing State: The
WebhookDelivery.processedAtfield is updated only after the routing logic completes, ensuring that a failed routing attempt will be retried if the job queue re-executes.
Sources: packages/ingestion/src/process-webhook.ts:121-140, packages/ingestion/src/process-webhook.ts:54-57
Summary
The Webhook Ingestion & Event Routing module provides a resilient gateway for GitHub events. By leveraging a dedicated intake route in the web process and a robust routing mechanism in the worker, the system can handle large volumes of events while maintaining data integrity through HMAC verification and database-level deduplication. This separation allows the AI review logic to operate at its own pace without blocking the incoming webhook stream.