Next.js Webhook Handling and Event-Driven Architecture

Next.js Webhook Handling and Event-Driven Architecture Building robust webhook handling in Next.js enables real-time responsiveness and event-driven architecture. This guide covers webhook security, retry mechanisms, event processing, and distributed system patterns for production applications. TL;DR Build production-ready event-driven systems using webhooks with Next.js and Supabase. You'll implement secure webhook endpoints, reliable event processing, retry mechanisms, and distributed system patterns for scalable applications. Prerequisites Next.js 14+ with API Routes experience Supabase database and Edge Functions knowledge Understanding of HTTP protocols and security Basic knowledge of distributed systems concepts Problem Statement Modern applications need to react to events from multiple sources: payment processors, third-party APIs, user actions, and system events. Simple polling is inefficient and doesn't scale. Event-driven architecture with webhooks provides real-time responsiveness but introduces complexity around security, reliability, and error handling. What Are Webhooks and How Do They Work? Webhooks push data to your application when events occur, while polling requires your app to repeatedly check for changes. Webhooks are more efficient, provide real-time updates, and reduce server load, but require proper security and error handling. How Do You Secure Webhook Endpoints in Next.js? Verify webhook signatures using HMAC, validate the source IP if possible, use HTTPS only, implement rate limiting, and validate payload structure. Never trust webhook data without verification - treat it as potentially malicious input. What Happens When Webhook Processing Fails? Implement retry mechanisms with exponential backoff, use dead letter queues for failed events, monitor webhook health, and consider using message queues for reliability. Most webhook providers retry failed deliveries automatically, so your endpoint should handle duplicate events gracefully. Step-by-Step Walkthrough 1. Webhook Infrastructure Setup Create a robust webhook handling system: -- Webhook events tracking table CREATE TABLE webhook_events ( id UUID PRIMARY KEY DEFAULT gen_random_uuid (), event_id TEXT UNIQUE NOT NULL , -- External event ID for idempotency source TEXT NOT NULL , -- 'stripe', 'github', 'supabase', etc. event_type TEXT NOT NULL , payload JSONB NOT NULL , status TEXT NOT NULL DEFAULT 'pending' , -- 'pending', 'processing', 'completed', 'failed' attempts INTEGER DEFAULT 0 , last_attempt_at TIMESTAMPTZ , completed_at TIMESTAMPTZ , error_message TEXT , created_at TIMESTAMPTZ DEFAULT NOW () ); -- Event processing jobs queue CREATE TABLE event_jobs ( id UUID PRIMARY KEY DEFAULT gen_random_uuid (), webhook_event_id UUID REFERENCES webhook_events ( id ) ON DELETE CASCADE , job_type TEXT NOT NULL , payload JSONB NOT NULL , status TEXT NOT NULL DEFAULT 'queued' , -- 'queued', 'processing', 'completed', 'failed' scheduled_for TIMESTAMPTZ DEFAULT NOW (), attempts INTEGER DEFAULT 0 , max_attempts INTEGER DEFAULT 3 , created_at TIMESTAMPTZ DEFAULT NOW (), updated_at TIMESTAMPTZ DEFAULT NOW () ); -- Indexes for performance CREATE INDEX idx_webhook_events_status ON webhook_events ( status ); CREATE INDEX idx_webhook_events_source_type ON webhook_events ( source , event_type ); CREATE INDEX idx_event_jobs_status_scheduled ON event_jobs ( status , scheduled_for ); 2. Secure Webhook Endpoint Implement a secure, generic webhook handler: // app/api/webhooks/[source]/route.ts import { NextRequest , NextResponse } from ' next/server ' import { createClient } from ' @/lib/supabase/server ' import { verifyWebhookSignature } from ' @/lib/webhook-security ' import { queueEventJob } from ' @/lib/event-queue ' interface WebhookConfig { secretKey : string signatureHeader : string verifySignature : ( payload : string , signature : string , secret : string ) => boolean } const WEBHOOK_CONFIGS : Record < string , WebhookConfig > = { stripe : { secretKey : proc