Event Driven Flow & Webhook Lifecycle

Relevant source files

The following files were used as context for generating this wiki page:

• apps/web/app/api/webhooks/github/route.ts
• packages/ingestion/src/process-webhook.ts
• packages/review/src/orchestrator.ts
• packages/db/prisma/schema.prisma
• README.md
• packages/github/src/review-client.ts

The Event Driven Flow & Webhook Lifecycle governs how the AI Code Reviewer system reacts to external signals from GitHub. The architecture is designed to decouple immediate HTTP responses from long-running AI processing tasks, ensuring the system remains responsive to GitHub's delivery requirements while managing complex asynchronous workflows like code analysis and LLM-based reviews.

This lifecycle spans two primary processes: the Web Server (Next.js), which acts as the ingestion point, and the Worker Process (Node.js), which executes the business logic associated with each event. These processes communicate through a PostgreSQL-backed job queue (pg-boss), ensuring transactional reliability and idempotency for every processed webhook.

Sources: README.md:65-79, apps/web/app/api/webhooks/github/route.ts:7-22

Webhook Ingestion Phase

The ingestion phase occurs within the apps/web context. Its primary responsibility is to securely receive, validate, and persist the raw event data before handing off execution to the background worker.

Validation and Security

Every incoming request to /api/webhooks/github undergoes a series of checks:

1. Payload Size Guard: Content is capped at 25 MB to prevent memory exhaustion from large push events.
2. Signature Verification: The X-Hub-Signature-256 header is verified using HMAC-SHA256 with a timingSafeEqual comparison to prevent timing attacks.
3. Deduplication: The unique X-GitHub-Delivery ID is used to upsert a record in the WebhookDelivery table. If the ID already exists and is marked as processed, the system returns a 200 OK immediately without re-enqueuing.

Sources: apps/web/app/api/webhooks/github/route.ts:40-108, README.md:144-148

Ingestion Sequence

The following sequence diagram illustrates the flow from GitHub to the persistent job queue.

Webhook Processing & Routing

Once the worker picks up the webhook.process job, the createProcessWebhookHandler routes the event based on its type and action. This handler is the central dispatcher for the system's event-driven logic.

Supported Event Types

Event	Action(s)	Impacted Data / Job Triggered
pull_request	opened, synchronize, reopened	Creates AiReview (PENDING); Enqueues review.pr
push	Any	Enqueues index.file for incremental RAG indexing
installation	suspend, unsuspend	Updates Installation.suspended flag
installation_repositories	added, removed	Upserts Repository rows or marks them as disabled
pull_request_review_comment	created	Enqueues review.process_developer_comment

Sources: packages/ingestion/src/process-webhook.ts:31-52, packages/db/prisma/schema.prisma:297-310

Pull Request Flow Logic

When a pull_request event is received, the system validates the repository's enabled status and ensures the PR is not a draft. It creates an AiReview record in a PENDING state to track the lifecycle of the specific commit SHA being reviewed.

Sources: packages/ingestion/src/process-webhook.ts:89-137

Review Lifecycle (Async Phase)

The review.pr job is the most resource-intensive part of the lifecycle. It involves multiple external API calls and AI orchestrations.

Orchestration Flow

The orchestrator.ts manages the transition of an AiReview through several states:

1. PENDING to RUNNING: Marks the start of the analysis.
2. Filtering: Skips files based on ReviewConfiguration (ignore paths, max file caps).
3. AI Analysis: For each file, the orchestrator fetches the diff, retrieves similar code chunks (Layer 1 context), and calls the LLM.
4. Validation: Every LLM-generated comment is validated against the diff to ensure the line number is "commentable." Invalid hallucinations are dropped.
5. Posting: Aggregated comments and a summary are posted to GitHub as a single COMMENT review.
6. Completion: Updates status to COMPLETED and stores the githubReviewId.

Sources: packages/review/src/orchestrator.ts:35-85, packages/review/src/orchestrator.ts:175-235, README.md:25-41

AI Review Lifecycle Diagram

Data Models for Lifecycle Tracking

The prisma.schema defines several models essential for maintaining the state of the event flow and ensuring idempotency.

Key Lifecycle Entities

• WebhookDelivery: Stores every raw payload. The processedAt field acts as a lock to prevent duplicate processing of re-delivered hooks.
• AiReview: Tracks the status of a review (PENDING, RUNNING, COMPLETED, FAILED, SKIPPED).
• IngestionState: An enum on the Repository model (DISCOVERING, CHUNKING, ACTIVE, etc.) used to track initial codebase indexing progress.

Sources: packages/db/prisma/schema.prisma:297-310, packages/db/prisma/schema.prisma:356-378, packages/db/prisma/schema.prisma:73-82

Summary of Lifecycle Transitions

The system ensures that every GitHub interaction is traceable and recoverable. By storing the WebhookDelivery first and processing it via a queue, the AI Code Reviewer can handle GitHub's 10-second timeout while performing LLM operations that typically take 15–40 seconds. The transition from PENDING to COMPLETED for an AiReview provides a clear audit trail of AI activity per commit.

Sources: README.md:46-53, packages/review/src/orchestrator.ts:240-250