@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-04-platform-integration.md

@@ -1,629 +1,629 @@
-# Module 4: Platform Integration
-
-**Level:** Intermediate
-**Estimated Time:** 30 minutes
-
-## Overview
-
-This module covers webhook validation integration across different platforms and frameworks. You'll learn patterns for Express.js, Next.js, AWS Lambda, and other Node.js environments.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- Integrate webhook validation in Express.js applications
-- Implement validation in Next.js API routes
-- Create AWS Lambda webhook handlers with validation
-- Handle raw body extraction across platforms
-- Build serverless webhook validators
-
----
-
-## Express.js Integration
-
-### Complete Express Webhook Endpoint
-
-```typescript
-import express from 'express';
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-const app = express();
-
-// CRITICAL: Use express.raw() to preserve original body
-app.use(express.raw({ type: 'application/json' }));
-
-// Initialize services
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-const validator = new WebhookValidationService({
-  strictValidation: true
-}, logger);
-
-app.post('/webhooks/fluent', async (req, res) => {
-  try {
-    // Get public key
-    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-    if (!publicKey) {
-      logger.error('Missing FLUENT_WEBHOOK_PUBLIC_KEY environment variable');
-      return res.status(500).json({ error: 'Server configuration error' });
-    }
-
-    // Extract raw body (Buffer to string)
-    const rawBody = req.body.toString('utf8');
-
-    // Validate webhook
-    const result = await validator.validateWebhook(
-      rawBody,
-      req.headers as Record<string, string>,
-      publicKey
-    );
-
-    // Handle validation failure
-    if (!result.isValid) {
-      logger.warn('Webhook validation failed', {
-        error: result.error,
-        algorithm: result.algorithm,
-        ip: req.ip
-      });
-      return res.status(401).json({ error: 'Invalid signature' });
-    }
-
-    // Log successful validation
-    logger.info('Webhook validated successfully', {
-      algorithm: result.algorithm
-    });
-
-    // Process webhook
-    const data = JSON.parse(rawBody);
-    await processWebhook(data);
-
-    res.status(200).json({ success: true, eventId: data.eventId });
-
-  } catch (error) {
-    logger.error('Webhook processing error', { error });
-    res.status(500).json({ error: 'Internal server error' });
-  }
-});
-
-app.listen(3000, () => {
-  console.log('Webhook server listening on port 3000');
-});
-
-async function processWebhook(data: any): Promise<void> {
-  console.log('Processing webhook:', data);
-  // Your business logic here
-}
-```
-
-### Express Raw Body Middleware
-
-```typescript
-import express, { Request, Response, NextFunction } from 'express';
-
-// Custom middleware to capture raw body
-function rawBodyMiddleware(req: Request, res: Response, next: NextFunction) {
-  let data = '';
-
-  req.setEncoding('utf8');
-  req.on('data', (chunk) => {
-    data += chunk;
-  });
-  req.on('end', () => {
-    (req as any).rawBody = data;
-    next();
-  });
-}
-
-app.use(rawBodyMiddleware);
-app.use(express.json());  // Also parse JSON for convenience
-
-app.post('/webhooks/fluent', async (req, res) => {
-  const rawBody = (req as any).rawBody;  // Use raw body for validation
-  const data = req.body;                 // Use parsed body for processing
-
-  const result = await validator.validateWebhook(rawBody, req.headers, publicKey);
-  // ...
-});
-```
-
----
-
-## Next.js API Routes
-
-### Next.js 13+ App Router
-
-```typescript
-// app/api/webhooks/fluent/route.ts
-import { NextRequest, NextResponse } from 'next/server';
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-export async function POST(request: NextRequest) {
-  try {
-    // Initialize services
-    const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-    const validator = new WebhookValidationService({
-      strictValidation: true
-    }, logger);
-
-    // Get public key
-    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-    if (!publicKey) {
-      return NextResponse.json(
-        { error: 'Server configuration error' },
-        { status: 500 }
-      );
-    }
-
-    // Extract raw body
-    const rawBody = await request.text();
-
-    // Convert headers to object
-    const headers: Record<string, string> = {};
-    request.headers.forEach((value, key) => {
-      headers[key] = value;
-    });
-
-    // Validate webhook
-    const result = await validator.validateWebhook(
-      rawBody,
-      headers,
-      publicKey
-    );
-
-    if (!result.isValid) {
-      logger.warn('Invalid webhook signature', { error: result.error });
-      return NextResponse.json(
-        { error: 'Invalid signature' },
-        { status: 401 }
-      );
-    }
-
-    // Process webhook
-    const data = JSON.parse(rawBody);
-    await processWebhook(data);
-
-    return NextResponse.json({
-      success: true,
-      eventId: data.eventId
-    });
-
-  } catch (error) {
-    console.error('Webhook error:', error);
-    return NextResponse.json(
-      { error: 'Internal server error' },
-      { status: 500 }
-    );
-  }
-}
-
-async function processWebhook(data: any): Promise<void> {
-  console.log('Processing webhook:', data);
-}
-```
-
-### Next.js Pages Router
-
-```typescript
-// pages/api/webhooks/fluent.ts
-import type { NextApiRequest, NextApiResponse } from 'next';
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Disable body parsing to get raw body
-export const config = {
-  api: {
-    bodyParser: false
-  }
-};
-
-export default async function handler(
-  req: NextApiRequest,
-  res: NextApiResponse
-) {
-  if (req.method !== 'POST') {
-    return res.status(405).json({ error: 'Method not allowed' });
-  }
-
-  try {
-    // Read raw body
-    const rawBody = await getRawBody(req);
-
-    // Initialize validator
-    const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-    const validator = new WebhookValidationService({
-      strictValidation: true
-    }, logger);
-
-    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-    if (!publicKey) {
-      return res.status(500).json({ error: 'Configuration error' });
-    }
-
-    // Validate
-    const result = await validator.validateWebhook(
-      rawBody,
-      req.headers as Record<string, string>,
-      publicKey
-    );
-
-    if (!result.isValid) {
-      return res.status(401).json({ error: 'Invalid signature' });
-    }
-
-    // Process
-    const data = JSON.parse(rawBody);
-    await processWebhook(data);
-
-    res.status(200).json({ success: true });
-
-  } catch (error) {
-    console.error('Error:', error);
-    res.status(500).json({ error: 'Internal server error' });
-  }
-}
-
-// Helper to read raw body
-async function getRawBody(req: NextApiRequest): Promise<string> {
-  return new Promise((resolve, reject) => {
-    let data = '';
-    req.setEncoding('utf8');
-    req.on('data', (chunk) => (data += chunk));
-    req.on('end', () => resolve(data));
-    req.on('error', reject);
-  });
-}
-
-async function processWebhook(data: any): Promise<void> {
-  console.log('Processing:', data);
-}
-```
-
----
-
-## AWS Lambda
-
-### Lambda Handler with Validation
-
-```typescript
-import {
-  APIGatewayProxyEvent,
-  APIGatewayProxyResult,
-  Context
-} from 'aws-lambda';
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-export async function handler(
-  event: APIGatewayProxyEvent,
-  context: Context
-): Promise<APIGatewayProxyResult> {
-  try {
-    // Initialize services
-    const logger = toStructuredLogger(createConsoleLogger(), { service: 'lambda-webhook' });
-    const validator = new WebhookValidationService({
-      strictValidation: true
-    }, logger);
-
-    // Get public key from environment
-    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-    if (!publicKey) {
-      return {
-        statusCode: 500,
-        body: JSON.stringify({ error: 'Configuration error' })
-      };
-    }
-
-    // Extract raw body (base64 decode if needed)
-    const rawBody = event.isBase64Encoded
-      ? Buffer.from(event.body || '', 'base64').toString('utf8')
-      : event.body || '';
-
-    // Convert headers to lowercase (API Gateway normalizes)
-    const headers: Record<string, string> = {};
-    Object.entries(event.headers || {}).forEach(([key, value]) => {
-      headers[key.toLowerCase()] = value || '';
-    });
-
-    // Validate webhook
-    const result = await validator.validateWebhook(
-      rawBody,
-      headers,
-      publicKey
-    );
-
-    if (!result.isValid) {
-      logger.warn('Validation failed', { error: result.error });
-      return {
-        statusCode: 401,
-        body: JSON.stringify({ error: 'Invalid signature' })
-      };
-    }
-
-    // Process webhook
-    const data = JSON.parse(rawBody);
-    await processWebhook(data);
-
-    return {
-      statusCode: 200,
-      body: JSON.stringify({ success: true, eventId: data.eventId })
-    };
-
-  } catch (error) {
-    console.error('Lambda error:', error);
-    return {
-      statusCode: 500,
-      body: JSON.stringify({ error: 'Internal server error' })
-    };
-  }
-}
-
-async function processWebhook(data: any): Promise<void> {
-  console.log('Processing webhook:', data);
-}
-```
-
----
-
-## Fastify
-
-### Fastify Webhook Route
-
-```typescript
-import Fastify from 'fastify';
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-const fastify = Fastify({ logger: true });
-
-// Register raw body parser
-fastify.addContentTypeParser(
-  'application/json',
-  { parseAs: 'string' },
-  (req, body, done) => {
-    done(null, body);
-  }
-);
-
-fastify.post('/webhooks/fluent', async (request, reply) => {
-  try {
-    // Initialize validator
-    const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-    const validator = new WebhookValidationService({
-      strictValidation: true
-    }, logger);
-
-    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-    if (!publicKey) {
-      return reply.code(500).send({ error: 'Configuration error' });
-    }
-
-    // Raw body is preserved by custom content type parser
-    const rawBody = request.body as string;
-
-    // Validate
-    const result = await validator.validateWebhook(
-      rawBody,
-      request.headers as Record<string, string>,
-      publicKey
-    );
-
-    if (!result.isValid) {
-      return reply.code(401).send({ error: 'Invalid signature' });
-    }
-
-    // Process
-    const data = JSON.parse(rawBody);
-    await processWebhook(data);
-
-    return reply.code(200).send({ success: true });
-
-  } catch (error) {
-    request.log.error(error);
-    return reply.code(500).send({ error: 'Internal error' });
-  }
-});
-
-fastify.listen({ port: 3000 }, (err) => {
-  if (err) throw err;
-  console.log('Server listening on port 3000');
-});
-
-async function processWebhook(data: any): Promise<void> {
-  console.log('Processing:', data);
-}
-```
-
----
-
-## Node.js HTTP Server
-
-### Raw Node.js Webhook Server
-
-```typescript
-import http from 'http';
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-const validator = new WebhookValidationService({
-  strictValidation: true
-}, logger);
-
-const server = http.createServer(async (req, res) => {
-  if (req.method !== 'POST' || req.url !== '/webhooks/fluent') {
-    res.writeHead(404);
-    res.end('Not found');
-    return;
-  }
-
-  try {
-    // Read raw body
-    const rawBody = await new Promise<string>((resolve, reject) => {
-      let data = '';
-      req.setEncoding('utf8');
-      req.on('data', (chunk) => (data += chunk));
-      req.on('end', () => resolve(data));
-      req.on('error', reject);
-    });
-
-    // Get public key
-    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-    if (!publicKey) {
-      res.writeHead(500);
-      res.end('Configuration error');
-      return;
-    }
-
-    // Validate
-    const result = await validator.validateWebhook(
-      rawBody,
-      req.headers as Record<string, string>,
-      publicKey
-    );
-
-    if (!result.isValid) {
-      res.writeHead(401);
-      res.end(JSON.stringify({ error: 'Invalid signature' }));
-      return;
-    }
-
-    // Process
-    const data = JSON.parse(rawBody);
-    await processWebhook(data);
-
-    res.writeHead(200, { 'Content-Type': 'application/json' });
-    res.end(JSON.stringify({ success: true }));
-
-  } catch (error) {
-    console.error('Error:', error);
-    res.writeHead(500);
-    res.end('Internal error');
-  }
-});
-
-server.listen(3000, () => {
-  console.log('Server listening on port 3000');
-});
-
-async function processWebhook(data: any): Promise<void> {
-  console.log('Processing:', data);
-}
-```
-
----
-
-## Platform-Specific Considerations
-
-### Express.js
-**Raw Body**: Use `express.raw({ type: 'application/json' })`
-**Headers**: `req.headers` (already object)
-**Body**: `req.body.toString('utf8')`
-
-### Next.js
-**Raw Body**: `await request.text()` (App Router) or custom parser (Pages Router)
-**Headers**: Convert `request.headers` to object
-**Config**: Disable body parser in Pages Router
-
-### AWS Lambda
-**Raw Body**: Handle `isBase64Encoded` flag
-**Headers**: Normalize to lowercase (API Gateway does this)
-**Body**: `event.body` (may be base64)
-
-### Fastify
-**Raw Body**: Custom content type parser with `parseAs: 'string'`
-**Headers**: `request.headers`
-**Body**: Cast to string after custom parser
-
-### Node.js HTTP
-**Raw Body**: Manual stream reading
-**Headers**: `req.headers`
-**Body**: UTF-8 encoded stream
-
----
-
-## Common Patterns Across Platforms
-
-### Pattern 1: Environment Variable for Public Key
-
-```typescript
-// All platforms
-const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-if (!publicKey) {
-  // Return 500 error
-}
-```
-
-### Pattern 2: Structured Error Response
-
-```typescript
-// All platforms should return consistent error format
-if (!result.isValid) {
-  return errorResponse(401, {
-    error: 'Invalid signature',
-    details: result.error,
-    timestamp: new Date().toISOString()
-  });
-}
-```
-
-### Pattern 3: Security Logging
-
-```typescript
-// Log validation failures across all platforms
-if (!result.isValid) {
-  logger.warn('Webhook validation failed', {
-    error: result.error,
-    algorithm: result.algorithm,
-    sourceIp: getClientIp(request),
-    timestamp: new Date().toISOString()
-  });
-}
-```
-
----
-
-## Key Takeaways
-
-- **Raw body is critical**: Each platform has different ways to access it
-- **Disable JSON parsing**: Use raw body parsers to preserve original bytes
-- **Headers vary**: Some platforms normalize headers (lowercase, etc.)
-- **Environment variables**: Consistent pattern across all platforms
-- **Error responses**: Return 401 for invalid signatures, 500 for config errors
-- **Logging**: Track validation failures for security monitoring
-
----
-
-## Practice Exercise
-
-Choose your platform and implement a complete webhook endpoint with validation.
-
----
-
-## Next Steps
-
-Continue to [Module 5: Configuration](./webhook-validation-05-configuration.md) to learn about advanced configuration options and factory methods.
-
----
-
-## Further Reading
-
-- [Module 6: Error Handling](./webhook-validation-06-error-handling.md) - Comprehensive error handling
-- [Module 7: API Reference](../../auto-pagination/modules/auto-pagination-07-api-reference.md) - Complete API documentation
+# Module 4: Platform Integration
+
+**Level:** Intermediate
+**Estimated Time:** 30 minutes
+
+## Overview
+
+This module covers webhook validation integration across different platforms and frameworks. You'll learn patterns for Express.js, Next.js, AWS Lambda, and other Node.js environments.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- Integrate webhook validation in Express.js applications
+- Implement validation in Next.js API routes
+- Create AWS Lambda webhook handlers with validation
+- Handle raw body extraction across platforms
+- Build serverless webhook validators
+
+---
+
+## Express.js Integration
+
+### Complete Express Webhook Endpoint
+
+```typescript
+import express from 'express';
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+const app = express();
+
+// CRITICAL: Use express.raw() to preserve original body
+app.use(express.raw({ type: 'application/json' }));
+
+// Initialize services
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+const validator = new WebhookValidationService({
+  strictValidation: true
+}, logger);
+
+app.post('/webhooks/fluent', async (req, res) => {
+  try {
+    // Get public key
+    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+    if (!publicKey) {
+      logger.error('Missing FLUENT_WEBHOOK_PUBLIC_KEY environment variable');
+      return res.status(500).json({ error: 'Server configuration error' });
+    }
+
+    // Extract raw body (Buffer to string)
+    const rawBody = req.body.toString('utf8');
+
+    // Validate webhook
+    const result = await validator.validateWebhook(
+      rawBody,
+      req.headers as Record<string, string>,
+      publicKey
+    );
+
+    // Handle validation failure
+    if (!result.isValid) {
+      logger.warn('Webhook validation failed', {
+        error: result.error,
+        algorithm: result.algorithm,
+        ip: req.ip
+      });
+      return res.status(401).json({ error: 'Invalid signature' });
+    }
+
+    // Log successful validation
+    logger.info('Webhook validated successfully', {
+      algorithm: result.algorithm
+    });
+
+    // Process webhook
+    const data = JSON.parse(rawBody);
+    await processWebhook(data);
+
+    res.status(200).json({ success: true, eventId: data.eventId });
+
+  } catch (error) {
+    logger.error('Webhook processing error', { error });
+    res.status(500).json({ error: 'Internal server error' });
+  }
+});
+
+app.listen(3000, () => {
+  console.log('Webhook server listening on port 3000');
+});
+
+async function processWebhook(data: any): Promise<void> {
+  console.log('Processing webhook:', data);
+  // Your business logic here
+}
+```
+
+### Express Raw Body Middleware
+
+```typescript
+import express, { Request, Response, NextFunction } from 'express';
+
+// Custom middleware to capture raw body
+function rawBodyMiddleware(req: Request, res: Response, next: NextFunction) {
+  let data = '';
+
+  req.setEncoding('utf8');
+  req.on('data', (chunk) => {
+    data += chunk;
+  });
+  req.on('end', () => {
+    (req as any).rawBody = data;
+    next();
+  });
+}
+
+app.use(rawBodyMiddleware);
+app.use(express.json());  // Also parse JSON for convenience
+
+app.post('/webhooks/fluent', async (req, res) => {
+  const rawBody = (req as any).rawBody;  // Use raw body for validation
+  const data = req.body;                 // Use parsed body for processing
+
+  const result = await validator.validateWebhook(rawBody, req.headers, publicKey);
+  // ...
+});
+```
+
+---
+
+## Next.js API Routes
+
+### Next.js 13+ App Router
+
+```typescript
+// app/api/webhooks/fluent/route.ts
+import { NextRequest, NextResponse } from 'next/server';
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+export async function POST(request: NextRequest) {
+  try {
+    // Initialize services
+    const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+    const validator = new WebhookValidationService({
+      strictValidation: true
+    }, logger);
+
+    // Get public key
+    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+    if (!publicKey) {
+      return NextResponse.json(
+        { error: 'Server configuration error' },
+        { status: 500 }
+      );
+    }
+
+    // Extract raw body
+    const rawBody = await request.text();
+
+    // Convert headers to object
+    const headers: Record<string, string> = {};
+    request.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    // Validate webhook
+    const result = await validator.validateWebhook(
+      rawBody,
+      headers,
+      publicKey
+    );
+
+    if (!result.isValid) {
+      logger.warn('Invalid webhook signature', { error: result.error });
+      return NextResponse.json(
+        { error: 'Invalid signature' },
+        { status: 401 }
+      );
+    }
+
+    // Process webhook
+    const data = JSON.parse(rawBody);
+    await processWebhook(data);
+
+    return NextResponse.json({
+      success: true,
+      eventId: data.eventId
+    });
+
+  } catch (error) {
+    console.error('Webhook error:', error);
+    return NextResponse.json(
+      { error: 'Internal server error' },
+      { status: 500 }
+    );
+  }
+}
+
+async function processWebhook(data: any): Promise<void> {
+  console.log('Processing webhook:', data);
+}
+```
+
+### Next.js Pages Router
+
+```typescript
+// pages/api/webhooks/fluent.ts
+import type { NextApiRequest, NextApiResponse } from 'next';
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Disable body parsing to get raw body
+export const config = {
+  api: {
+    bodyParser: false
+  }
+};
+
+export default async function handler(
+  req: NextApiRequest,
+  res: NextApiResponse
+) {
+  if (req.method !== 'POST') {
+    return res.status(405).json({ error: 'Method not allowed' });
+  }
+
+  try {
+    // Read raw body
+    const rawBody = await getRawBody(req);
+
+    // Initialize validator
+    const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+    const validator = new WebhookValidationService({
+      strictValidation: true
+    }, logger);
+
+    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+    if (!publicKey) {
+      return res.status(500).json({ error: 'Configuration error' });
+    }
+
+    // Validate
+    const result = await validator.validateWebhook(
+      rawBody,
+      req.headers as Record<string, string>,
+      publicKey
+    );
+
+    if (!result.isValid) {
+      return res.status(401).json({ error: 'Invalid signature' });
+    }
+
+    // Process
+    const data = JSON.parse(rawBody);
+    await processWebhook(data);
+
+    res.status(200).json({ success: true });
+
+  } catch (error) {
+    console.error('Error:', error);
+    res.status(500).json({ error: 'Internal server error' });
+  }
+}
+
+// Helper to read raw body
+async function getRawBody(req: NextApiRequest): Promise<string> {
+  return new Promise((resolve, reject) => {
+    let data = '';
+    req.setEncoding('utf8');
+    req.on('data', (chunk) => (data += chunk));
+    req.on('end', () => resolve(data));
+    req.on('error', reject);
+  });
+}
+
+async function processWebhook(data: any): Promise<void> {
+  console.log('Processing:', data);
+}
+```
+
+---
+
+## AWS Lambda
+
+### Lambda Handler with Validation
+
+```typescript
+import {
+  APIGatewayProxyEvent,
+  APIGatewayProxyResult,
+  Context
+} from 'aws-lambda';
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+export async function handler(
+  event: APIGatewayProxyEvent,
+  context: Context
+): Promise<APIGatewayProxyResult> {
+  try {
+    // Initialize services
+    const logger = toStructuredLogger(createConsoleLogger(), { service: 'lambda-webhook' });
+    const validator = new WebhookValidationService({
+      strictValidation: true
+    }, logger);
+
+    // Get public key from environment
+    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+    if (!publicKey) {
+      return {
+        statusCode: 500,
+        body: JSON.stringify({ error: 'Configuration error' })
+      };
+    }
+
+    // Extract raw body (base64 decode if needed)
+    const rawBody = event.isBase64Encoded
+      ? Buffer.from(event.body || '', 'base64').toString('utf8')
+      : event.body || '';
+
+    // Convert headers to lowercase (API Gateway normalizes)
+    const headers: Record<string, string> = {};
+    Object.entries(event.headers || {}).forEach(([key, value]) => {
+      headers[key.toLowerCase()] = value || '';
+    });
+
+    // Validate webhook
+    const result = await validator.validateWebhook(
+      rawBody,
+      headers,
+      publicKey
+    );
+
+    if (!result.isValid) {
+      logger.warn('Validation failed', { error: result.error });
+      return {
+        statusCode: 401,
+        body: JSON.stringify({ error: 'Invalid signature' })
+      };
+    }
+
+    // Process webhook
+    const data = JSON.parse(rawBody);
+    await processWebhook(data);
+
+    return {
+      statusCode: 200,
+      body: JSON.stringify({ success: true, eventId: data.eventId })
+    };
+
+  } catch (error) {
+    console.error('Lambda error:', error);
+    return {
+      statusCode: 500,
+      body: JSON.stringify({ error: 'Internal server error' })
+    };
+  }
+}
+
+async function processWebhook(data: any): Promise<void> {
+  console.log('Processing webhook:', data);
+}
+```
+
+---
+
+## Fastify
+
+### Fastify Webhook Route
+
+```typescript
+import Fastify from 'fastify';
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+const fastify = Fastify({ logger: true });
+
+// Register raw body parser
+fastify.addContentTypeParser(
+  'application/json',
+  { parseAs: 'string' },
+  (req, body, done) => {
+    done(null, body);
+  }
+);
+
+fastify.post('/webhooks/fluent', async (request, reply) => {
+  try {
+    // Initialize validator
+    const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+    const validator = new WebhookValidationService({
+      strictValidation: true
+    }, logger);
+
+    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+    if (!publicKey) {
+      return reply.code(500).send({ error: 'Configuration error' });
+    }
+
+    // Raw body is preserved by custom content type parser
+    const rawBody = request.body as string;
+
+    // Validate
+    const result = await validator.validateWebhook(
+      rawBody,
+      request.headers as Record<string, string>,
+      publicKey
+    );
+
+    if (!result.isValid) {
+      return reply.code(401).send({ error: 'Invalid signature' });
+    }
+
+    // Process
+    const data = JSON.parse(rawBody);
+    await processWebhook(data);
+
+    return reply.code(200).send({ success: true });
+
+  } catch (error) {
+    request.log.error(error);
+    return reply.code(500).send({ error: 'Internal error' });
+  }
+});
+
+fastify.listen({ port: 3000 }, (err) => {
+  if (err) throw err;
+  console.log('Server listening on port 3000');
+});
+
+async function processWebhook(data: any): Promise<void> {
+  console.log('Processing:', data);
+}
+```
+
+---
+
+## Node.js HTTP Server
+
+### Raw Node.js Webhook Server
+
+```typescript
+import http from 'http';
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+const validator = new WebhookValidationService({
+  strictValidation: true
+}, logger);
+
+const server = http.createServer(async (req, res) => {
+  if (req.method !== 'POST' || req.url !== '/webhooks/fluent') {
+    res.writeHead(404);
+    res.end('Not found');
+    return;
+  }
+
+  try {
+    // Read raw body
+    const rawBody = await new Promise<string>((resolve, reject) => {
+      let data = '';
+      req.setEncoding('utf8');
+      req.on('data', (chunk) => (data += chunk));
+      req.on('end', () => resolve(data));
+      req.on('error', reject);
+    });
+
+    // Get public key
+    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+    if (!publicKey) {
+      res.writeHead(500);
+      res.end('Configuration error');
+      return;
+    }
+
+    // Validate
+    const result = await validator.validateWebhook(
+      rawBody,
+      req.headers as Record<string, string>,
+      publicKey
+    );
+
+    if (!result.isValid) {
+      res.writeHead(401);
+      res.end(JSON.stringify({ error: 'Invalid signature' }));
+      return;
+    }
+
+    // Process
+    const data = JSON.parse(rawBody);
+    await processWebhook(data);
+
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ success: true }));
+
+  } catch (error) {
+    console.error('Error:', error);
+    res.writeHead(500);
+    res.end('Internal error');
+  }
+});
+
+server.listen(3000, () => {
+  console.log('Server listening on port 3000');
+});
+
+async function processWebhook(data: any): Promise<void> {
+  console.log('Processing:', data);
+}
+```
+
+---
+
+## Platform-Specific Considerations
+
+### Express.js
+**Raw Body**: Use `express.raw({ type: 'application/json' })`
+**Headers**: `req.headers` (already object)
+**Body**: `req.body.toString('utf8')`
+
+### Next.js
+**Raw Body**: `await request.text()` (App Router) or custom parser (Pages Router)
+**Headers**: Convert `request.headers` to object
+**Config**: Disable body parser in Pages Router
+
+### AWS Lambda
+**Raw Body**: Handle `isBase64Encoded` flag
+**Headers**: Normalize to lowercase (API Gateway does this)
+**Body**: `event.body` (may be base64)
+
+### Fastify
+**Raw Body**: Custom content type parser with `parseAs: 'string'`
+**Headers**: `request.headers`
+**Body**: Cast to string after custom parser
+
+### Node.js HTTP
+**Raw Body**: Manual stream reading
+**Headers**: `req.headers`
+**Body**: UTF-8 encoded stream
+
+---
+
+## Common Patterns Across Platforms
+
+### Pattern 1: Environment Variable for Public Key
+
+```typescript
+// All platforms
+const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+if (!publicKey) {
+  // Return 500 error
+}
+```
+
+### Pattern 2: Structured Error Response
+
+```typescript
+// All platforms should return consistent error format
+if (!result.isValid) {
+  return errorResponse(401, {
+    error: 'Invalid signature',
+    details: result.error,
+    timestamp: new Date().toISOString()
+  });
+}
+```
+
+### Pattern 3: Security Logging
+
+```typescript
+// Log validation failures across all platforms
+if (!result.isValid) {
+  logger.warn('Webhook validation failed', {
+    error: result.error,
+    algorithm: result.algorithm,
+    sourceIp: getClientIp(request),
+    timestamp: new Date().toISOString()
+  });
+}
+```
+
+---
+
+## Key Takeaways
+
+- **Raw body is critical**: Each platform has different ways to access it
+- **Disable JSON parsing**: Use raw body parsers to preserve original bytes
+- **Headers vary**: Some platforms normalize headers (lowercase, etc.)
+- **Environment variables**: Consistent pattern across all platforms
+- **Error responses**: Return 401 for invalid signatures, 500 for config errors
+- **Logging**: Track validation failures for security monitoring
+
+---
+
+## Practice Exercise
+
+Choose your platform and implement a complete webhook endpoint with validation.
+
+---
+
+## Next Steps
+
+Continue to [Module 5: Configuration](./webhook-validation-05-configuration.md) to learn about advanced configuration options and factory methods.
+
+---
+
+## Further Reading
+
+- [Module 6: Error Handling](./webhook-validation-06-error-handling.md) - Comprehensive error handling
+- [Module 7: API Reference](../../auto-pagination/modules/auto-pagination-07-api-reference.md) - Complete API documentation