@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/02-CORE-GUIDES/api-reference/modules/api-reference-09-webhook-validation.md

@@ -1,514 +1,514 @@
-# Module 09: Webhook Validation
-
-**Level:** Intermediate
-**Category:** Security & Integration
-
-## Overview
-
-Webhook validation ensures that incoming webhook requests from Fluent Commerce are authentic and haven't been tampered with. The SDK provides `parseWebhookRequest()` for HMAC signature verification, preventing security vulnerabilities from forged webhooks.
-
-## Table of Contents
-
-- [Why Webhook Validation](#why-webhook-validation)
-- [parseWebhookRequest() Function](#parsewebhookrequest-function)
-- [HMAC Signature Verification](#hmac-signature-verification)
-- [Webhook Security](#webhook-security)
-- [Platform Integration](#platform-integration)
-- [Error Handling](#error-handling)
-- [Common Patterns](#common-patterns)
-- [Troubleshooting](#troubleshooting)
-- [See Also](#see-also)
-
----
-
-## Why Webhook Validation
-
-Without validation, malicious actors can:
-- Send forged events to trigger unintended actions
-- Inject malicious payloads
-- Cause data corruption or unauthorized access
-- Perform denial-of-service attacks
-
-**Security Benefits:**
-- Cryptographic proof of authenticity
-- Tamper detection
-- Replay attack prevention
-- Integration integrity
-
----
-
-## parseWebhookRequest() Function
-
-The SDK provides a top-level function for webhook validation:
-
-```typescript
-import { parseWebhookRequest } from '@fluentcommerce/fc-connect-sdk';
-
-// Validate incoming webhook
-const result = await parseWebhookRequest({
-  body: requestBody,        // Raw request body (string or Buffer)
-  signature: headerValue,   // X-Fluent-Signature header
-  secret: process.env.WEBHOOK_SECRET,  // Your webhook secret
-  timestamp: Date.now(),    // Current timestamp
-  toleranceMs: 300000      // 5 minutes tolerance (default)
-});
-
-if (result.valid) {
-  console.log('Webhook authenticated:', result.payload);
-  // Process webhook event...
-} else {
-  console.error('Invalid webhook:', result.error);
-  // Reject request with 401
-}
-```
-
-**Function Signature:**
-
-```typescript
-function parseWebhookRequest(options: {
-  body: string | Buffer;      // Request body
-  signature: string;          // X-Fluent-Signature header
-  secret: string;             // Webhook secret from Fluent
-  timestamp?: number;         // Current time (default: Date.now())
-  toleranceMs?: number;       // Clock skew tolerance (default: 300000)
-}): Promise<WebhookValidationResult>;
-
-interface WebhookValidationResult {
-  valid: boolean;             // True if signature valid
-  payload: any;               // Parsed webhook payload (if valid)
-  error?: string;             // Error message (if invalid)
-  timestamp?: number;         // Webhook timestamp
-}
-```
-
----
-
-## HMAC Signature Verification
-
-Fluent Commerce signs webhooks using HMAC-SHA256:
-
-### How It Works
-
-1. **Fluent sends webhook:**
-   - Generates HMAC signature: `HMAC-SHA256(secret, payload)`
-   - Includes signature in `X-Fluent-Signature` header
-
-2. **Your service receives webhook:**
-   - Extracts body and signature
-   - Recomputes HMAC with your secret
-   - Compares computed signature with header value
-
-3. **SDK validates:**
-   - Parses signature format: `t=timestamp,v1=signature`
-   - Checks timestamp within tolerance window
-   - Verifies HMAC matches
-
-### Signature Format
-
-```
-X-Fluent-Signature: t=1640995200,v1=abc123def456...
-```
-
-**Components:**
-- `t`: Unix timestamp when webhook sent
-- `v1`: HMAC-SHA256 signature (hex)
-
-### Verification Algorithm
-
-```typescript
-// Simplified (SDK does this internally)
-function verifySignature(body: string, signature: string, secret: string): boolean {
-  // Parse signature header
-  const parts = signature.split(',');
-  const timestamp = parts.find(p => p.startsWith('t=')).split('=')[1];
-  const receivedSig = parts.find(p => p.startsWith('v1=')).split('=')[1];
-
-  // Compute expected signature
-  const payload = `${timestamp}.${body}`;
-  const expectedSig = crypto
-    .createHmac('sha256', secret)
-    .update(payload)
-    .digest('hex');
-
-  // Constant-time comparison
-  return crypto.timingSafeEqual(
-    Buffer.from(receivedSig, 'hex'),
-    Buffer.from(expectedSig, 'hex')
-  );
-}
-```
-
----
-
-## Webhook Security
-
-### Best Practices
-
-**1. Always Validate Signatures**
-
-```typescript
-// ✅ CORRECT: Validate before processing
-const result = await parseWebhookRequest({ body, signature, secret });
-if (!result.valid) {
-  return new Response('Unauthorized', { status: 401 });
-}
-
-// Process event...
-
-// ❌ WRONG: Process without validation
-const payload = JSON.parse(body);
-await processEvent(payload);  // Insecure!
-```
-
-**2. Use Environment Variables for Secrets**
-
-```typescript
-// ✅ CORRECT: Secret from environment
-const secret = process.env.FLUENT_WEBHOOK_SECRET;
-
-// ❌ WRONG: Hardcoded secret
-const secret = 'my-secret-key';  // Never do this!
-```
-
-**3. Set Appropriate Tolerance**
-
-```typescript
-// ✅ CORRECT: 5-minute tolerance (default)
-const result = await parseWebhookRequest({
-  body,
-  signature,
-  secret,
-  toleranceMs: 300000  // 5 minutes
-});
-
-// ❌ WRONG: Too permissive
-const result = await parseWebhookRequest({
-  body,
-  signature,
-  secret,
-  toleranceMs: 3600000  // 1 hour - allows replay attacks!
-});
-```
-
-**4. Reject Invalid Webhooks**
-
-```typescript
-// ✅ CORRECT: Return 401 for invalid signatures
-if (!result.valid) {
-  console.warn('Invalid webhook signature:', result.error);
-  return new Response('Unauthorized', { status: 401 });
-}
-
-// ❌ WRONG: Process anyway
-if (!result.valid) {
-  console.warn('Invalid signature, but processing anyway...');
-  await processEvent(result.payload);  // Dangerous!
-}
-```
-
-### Common Security Mistakes
-
-| Mistake | Risk | Fix |
-|---------|------|-----|
-| Skip validation | Forged requests | Always validate |
-| Hardcode secrets | Secret leakage | Use environment variables |
-| Large tolerance | Replay attacks | Use 5-minute default |
-| Ignore errors | Data corruption | Return 401 on failure |
-
----
-
-## Platform Integration
-
-### Versori Webhooks
-
-```typescript
-import { webhook } from '@versori/run';
-import { parseWebhookRequest } from '@fluentcommerce/fc-connect-sdk';
-
-export const fluentWebhook = webhook('fluent-events', async (req, ctx) => {
-  const { log } = ctx;
-
-  // Extract signature header
-  const signature = req.headers.get('X-Fluent-Signature');
-  if (!signature) {
-    return new Response('Missing signature', { status: 401 });
-  }
-
-  // Validate webhook
-  const result = await parseWebhookRequest({
-    body: await req.text(),
-    signature,
-    secret: process.env.FLUENT_WEBHOOK_SECRET
-  });
-
-  if (!result.valid) {
-    log.warn('Invalid webhook', { error: result.error });
-    return new Response('Unauthorized', { status: 401 });
-  }
-
-  // Process validated event
-  log.info('Webhook received', { event: result.payload.eventName });
-  await processFluentEvent(result.payload);
-
-  return new Response('OK', { status: 200 });
-});
-```
-
-### Node.js Express
-
-```typescript
-import express from 'express';
-import { parseWebhookRequest } from '@fluentcommerce/fc-connect-sdk';
-
-const app = express();
-
-// IMPORTANT: Use raw body for signature verification
-app.post('/webhooks/fluent', express.raw({ type: 'application/json' }), async (req, res) => {
-  const signature = req.headers['x-fluent-signature'];
-
-  const result = await parseWebhookRequest({
-    body: req.body,  // Raw buffer
-    signature,
-    secret: process.env.FLUENT_WEBHOOK_SECRET
-  });
-
-  if (!result.valid) {
-    return res.status(401).send('Unauthorized');
-  }
-
-  await processEvent(result.payload);
-  res.status(200).send('OK');
-});
-```
-
-### Deno HTTP Server
-
-```typescript
-import { serve } from 'https://deno.land/std/http/server.ts';
-import { parseWebhookRequest } from '@fluentcommerce/fc-connect-sdk';
-
-serve(async (req) => {
-  if (req.url === '/webhooks/fluent') {
-    const signature = req.headers.get('X-Fluent-Signature');
-    const body = await req.text();
-
-    const result = await parseWebhookRequest({
-      body,
-      signature,
-      secret: Deno.env.get('FLUENT_WEBHOOK_SECRET')
-    });
-
-    if (!result.valid) {
-      return new Response('Unauthorized', { status: 401 });
-    }
-
-    await processEvent(result.payload);
-    return new Response('OK', { status: 200 });
-  }
-});
-```
-
----
-
-## Error Handling
-
-### Common Errors
-
-```typescript
-const result = await parseWebhookRequest({ body, signature, secret });
-
-if (!result.valid) {
-  switch (result.error) {
-    case 'Missing signature':
-      // No X-Fluent-Signature header
-      return new Response('Missing signature header', { status: 400 });
-
-    case 'Invalid signature format':
-      // Malformed signature (not t=...,v1=...)
-      return new Response('Bad signature format', { status: 400 });
-
-    case 'Timestamp too old':
-      // Request older than tolerance window
-      return new Response('Request expired', { status: 401 });
-
-    case 'Signature mismatch':
-      // HMAC doesn't match (wrong secret or tampered body)
-      return new Response('Unauthorized', { status: 401 });
-
-    default:
-      return new Response('Validation failed', { status: 401 });
-  }
-}
-```
-
-### Logging Validation Failures
-
-```typescript
-const result = await parseWebhookRequest({ body, signature, secret });
-
-if (!result.valid) {
-  // Log for security monitoring
-  log.warn('Webhook validation failed', {
-    error: result.error,
-    signature: signature.substring(0, 20) + '...',  // Truncate for logs
-    bodyLength: body.length,
-    timestamp: result.timestamp,
-    ip: req.headers.get('X-Forwarded-For')
-  });
-
-  return new Response('Unauthorized', { status: 401 });
-}
-```
-
----
-
-## Common Patterns
-
-### Pattern 1: Idempotent Processing
-
-```typescript
-const result = await parseWebhookRequest({ body, signature, secret });
-if (!result.valid) return unauthorized();
-
-const eventId = result.payload.id;
-
-// Check if already processed
-if (await stateService.isEventProcessed(eventId)) {
-  return new Response('Already processed', { status: 200 });
-}
-
-// Process event
-await processEvent(result.payload);
-
-// Mark as processed
-await stateService.markEventProcessed(eventId);
-
-return new Response('OK', { status: 200 });
-```
-
-### Pattern 2: Event Type Routing
-
-```typescript
-const result = await parseWebhookRequest({ body, signature, secret });
-if (!result.valid) return unauthorized();
-
-const { eventName, entity } = result.payload;
-
-switch (eventName) {
-  case 'ORDER.CREATED':
-    await handleOrderCreated(entity);
-    break;
-
-  case 'FULFILMENT.UPDATED':
-    await handleFulfilmentUpdated(entity);
-    break;
-
-  case 'INVENTORY.ADJUSTED':
-    await handleInventoryAdjusted(entity);
-    break;
-
-  default:
-    console.log(`Unhandled event: ${eventName}`);
-}
-
-return new Response('OK', { status: 200 });
-```
-
-### Pattern 3: Async Processing
-
-```typescript
-const result = await parseWebhookRequest({ body, signature, secret });
-if (!result.valid) return unauthorized();
-
-// Acknowledge webhook immediately
-queueForProcessing(result.payload);
-
-return new Response('Accepted', { status: 202 });
-
-// Process asynchronously
-async function queueForProcessing(payload) {
-  await messageQueue.publish('fluent-events', payload);
-}
-```
-
----
-
-## Troubleshooting
-
-### Issue 1: Always Getting "Signature mismatch"
-
-**Causes:**
-- Wrong webhook secret
-- Body modified before validation
-- JSON parsing before validation
-
-**Solutions:**
-```typescript
-// ✅ Use raw body for validation
-app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
-  const result = await parseWebhookRequest({
-    body: req.body,  // Raw buffer, not parsed JSON
-    signature: req.headers['x-fluent-signature'],
-    secret: process.env.FLUENT_WEBHOOK_SECRET
-  });
-});
-
-// ❌ WRONG: Parse JSON first
-app.post('/webhook', express.json(), async (req, res) => {
-  // Body already parsed - signature will fail!
-});
-```
-
-### Issue 2: "Timestamp too old" Errors
-
-**Causes:**
-- Server clock skew
-- Network delays
-- Tolerance too strict
-
-**Solutions:**
-```typescript
-// ✅ Increase tolerance if needed
-const result = await parseWebhookRequest({
-  body,
-  signature,
-  secret,
-  toleranceMs: 600000  // 10 minutes for slow networks
-});
-```
-
-### Issue 3: Missing Signature Header
-
-**Cause:** Header not forwarded by proxy/load balancer
-
-**Solution:**
-```typescript
-// Check different header names
-const signature =
-  req.headers.get('X-Fluent-Signature') ||
-  req.headers.get('x-fluent-signature') ||
-  req.headers.get('X-Fluent-Signature'.toLowerCase());
-```
-
----
-
-## See Also
-
-**Related Modules:**
-- [Module 01: Client API](./api-reference-01-client-api.md) - FluentClient creation
-- [Module 11: Error Handling](./api-reference-11-error-handling.md) - Error strategies
-
-**Complete Guides:**
-- [Webhook Validation Guide](../../webhook-validation/webhook-validation-readme.md) - Full webhook validation series
-- [Versori Webhook Patterns](../../../04-REFERENCE/platforms/versori/platforms-versori-webhook-connection-security.md)
-
-**Templates:**
-- [Generic XML Order Webhook](../../../01-TEMPLATES/versori/webhooks/template-webhook-generic-xml-order.md)
-- [ASN Purchase Order Webhook](../../../01-TEMPLATES/versori/webhooks/template-webhook-asn-purchase-order.md)
-
----
-
-**Navigation:**
-- [Back to Module List](./readme.md)
-- [Previous: Module 08 - Pagination](./api-reference-08-pagination.md)
-- [Next: Module 10 - Extraction](./api-reference-10-extraction.md)
+# Module 09: Webhook Validation
+
+**Level:** Intermediate
+**Category:** Security & Integration
+
+## Overview
+
+Webhook validation ensures that incoming webhook requests from Fluent Commerce are authentic and haven't been tampered with. The SDK provides `parseWebhookRequest()` for HMAC signature verification, preventing security vulnerabilities from forged webhooks.
+
+## Table of Contents
+
+- [Why Webhook Validation](#why-webhook-validation)
+- [parseWebhookRequest() Function](#parsewebhookrequest-function)
+- [HMAC Signature Verification](#hmac-signature-verification)
+- [Webhook Security](#webhook-security)
+- [Platform Integration](#platform-integration)
+- [Error Handling](#error-handling)
+- [Common Patterns](#common-patterns)
+- [Troubleshooting](#troubleshooting)
+- [See Also](#see-also)
+
+---
+
+## Why Webhook Validation
+
+Without validation, malicious actors can:
+- Send forged events to trigger unintended actions
+- Inject malicious payloads
+- Cause data corruption or unauthorized access
+- Perform denial-of-service attacks
+
+**Security Benefits:**
+- Cryptographic proof of authenticity
+- Tamper detection
+- Replay attack prevention
+- Integration integrity
+
+---
+
+## parseWebhookRequest() Function
+
+The SDK provides a top-level function for webhook validation:
+
+```typescript
+import { parseWebhookRequest } from '@fluentcommerce/fc-connect-sdk';
+
+// Validate incoming webhook
+const result = await parseWebhookRequest({
+  body: requestBody,        // Raw request body (string or Buffer)
+  signature: headerValue,   // X-Fluent-Signature header
+  secret: process.env.WEBHOOK_SECRET,  // Your webhook secret
+  timestamp: Date.now(),    // Current timestamp
+  toleranceMs: 300000      // 5 minutes tolerance (default)
+});
+
+if (result.valid) {
+  console.log('Webhook authenticated:', result.payload);
+  // Process webhook event...
+} else {
+  console.error('Invalid webhook:', result.error);
+  // Reject request with 401
+}
+```
+
+**Function Signature:**
+
+```typescript
+function parseWebhookRequest(options: {
+  body: string | Buffer;      // Request body
+  signature: string;          // X-Fluent-Signature header
+  secret: string;             // Webhook secret from Fluent
+  timestamp?: number;         // Current time (default: Date.now())
+  toleranceMs?: number;       // Clock skew tolerance (default: 300000)
+}): Promise<WebhookValidationResult>;
+
+interface WebhookValidationResult {
+  valid: boolean;             // True if signature valid
+  payload: any;               // Parsed webhook payload (if valid)
+  error?: string;             // Error message (if invalid)
+  timestamp?: number;         // Webhook timestamp
+}
+```
+
+---
+
+## HMAC Signature Verification
+
+Fluent Commerce signs webhooks using HMAC-SHA256:
+
+### How It Works
+
+1. **Fluent sends webhook:**
+   - Generates HMAC signature: `HMAC-SHA256(secret, payload)`
+   - Includes signature in `X-Fluent-Signature` header
+
+2. **Your service receives webhook:**
+   - Extracts body and signature
+   - Recomputes HMAC with your secret
+   - Compares computed signature with header value
+
+3. **SDK validates:**
+   - Parses signature format: `t=timestamp,v1=signature`
+   - Checks timestamp within tolerance window
+   - Verifies HMAC matches
+
+### Signature Format
+
+```
+X-Fluent-Signature: t=1640995200,v1=abc123def456...
+```
+
+**Components:**
+- `t`: Unix timestamp when webhook sent
+- `v1`: HMAC-SHA256 signature (hex)
+
+### Verification Algorithm
+
+```typescript
+// Simplified (SDK does this internally)
+function verifySignature(body: string, signature: string, secret: string): boolean {
+  // Parse signature header
+  const parts = signature.split(',');
+  const timestamp = parts.find(p => p.startsWith('t=')).split('=')[1];
+  const receivedSig = parts.find(p => p.startsWith('v1=')).split('=')[1];
+
+  // Compute expected signature
+  const payload = `${timestamp}.${body}`;
+  const expectedSig = crypto
+    .createHmac('sha256', secret)
+    .update(payload)
+    .digest('hex');
+
+  // Constant-time comparison
+  return crypto.timingSafeEqual(
+    Buffer.from(receivedSig, 'hex'),
+    Buffer.from(expectedSig, 'hex')
+  );
+}
+```
+
+---
+
+## Webhook Security
+
+### Best Practices
+
+**1. Always Validate Signatures**
+
+```typescript
+// ✅ CORRECT: Validate before processing
+const result = await parseWebhookRequest({ body, signature, secret });
+if (!result.valid) {
+  return new Response('Unauthorized', { status: 401 });
+}
+
+// Process event...
+
+// ❌ WRONG: Process without validation
+const payload = JSON.parse(body);
+await processEvent(payload);  // Insecure!
+```
+
+**2. Use Environment Variables for Secrets**
+
+```typescript
+// ✅ CORRECT: Secret from environment
+const secret = process.env.FLUENT_WEBHOOK_SECRET;
+
+// ❌ WRONG: Hardcoded secret
+const secret = 'my-secret-key';  // Never do this!
+```
+
+**3. Set Appropriate Tolerance**
+
+```typescript
+// ✅ CORRECT: 5-minute tolerance (default)
+const result = await parseWebhookRequest({
+  body,
+  signature,
+  secret,
+  toleranceMs: 300000  // 5 minutes
+});
+
+// ❌ WRONG: Too permissive
+const result = await parseWebhookRequest({
+  body,
+  signature,
+  secret,
+  toleranceMs: 3600000  // 1 hour - allows replay attacks!
+});
+```
+
+**4. Reject Invalid Webhooks**
+
+```typescript
+// ✅ CORRECT: Return 401 for invalid signatures
+if (!result.valid) {
+  console.warn('Invalid webhook signature:', result.error);
+  return new Response('Unauthorized', { status: 401 });
+}
+
+// ❌ WRONG: Process anyway
+if (!result.valid) {
+  console.warn('Invalid signature, but processing anyway...');
+  await processEvent(result.payload);  // Dangerous!
+}
+```
+
+### Common Security Mistakes
+
+| Mistake | Risk | Fix |
+|---------|------|-----|
+| Skip validation | Forged requests | Always validate |
+| Hardcode secrets | Secret leakage | Use environment variables |
+| Large tolerance | Replay attacks | Use 5-minute default |
+| Ignore errors | Data corruption | Return 401 on failure |
+
+---
+
+## Platform Integration
+
+### Versori Webhooks
+
+```typescript
+import { webhook } from '@versori/run';
+import { parseWebhookRequest } from '@fluentcommerce/fc-connect-sdk';
+
+export const fluentWebhook = webhook('fluent-events', async (req, ctx) => {
+  const { log } = ctx;
+
+  // Extract signature header
+  const signature = req.headers.get('X-Fluent-Signature');
+  if (!signature) {
+    return new Response('Missing signature', { status: 401 });
+  }
+
+  // Validate webhook
+  const result = await parseWebhookRequest({
+    body: await req.text(),
+    signature,
+    secret: process.env.FLUENT_WEBHOOK_SECRET
+  });
+
+  if (!result.valid) {
+    log.warn('Invalid webhook', { error: result.error });
+    return new Response('Unauthorized', { status: 401 });
+  }
+
+  // Process validated event
+  log.info('Webhook received', { event: result.payload.eventName });
+  await processFluentEvent(result.payload);
+
+  return new Response('OK', { status: 200 });
+});
+```
+
+### Node.js Express
+
+```typescript
+import express from 'express';
+import { parseWebhookRequest } from '@fluentcommerce/fc-connect-sdk';
+
+const app = express();
+
+// IMPORTANT: Use raw body for signature verification
+app.post('/webhooks/fluent', express.raw({ type: 'application/json' }), async (req, res) => {
+  const signature = req.headers['x-fluent-signature'];
+
+  const result = await parseWebhookRequest({
+    body: req.body,  // Raw buffer
+    signature,
+    secret: process.env.FLUENT_WEBHOOK_SECRET
+  });
+
+  if (!result.valid) {
+    return res.status(401).send('Unauthorized');
+  }
+
+  await processEvent(result.payload);
+  res.status(200).send('OK');
+});
+```
+
+### Deno HTTP Server
+
+```typescript
+import { serve } from 'https://deno.land/std/http/server.ts';
+import { parseWebhookRequest } from '@fluentcommerce/fc-connect-sdk';
+
+serve(async (req) => {
+  if (req.url === '/webhooks/fluent') {
+    const signature = req.headers.get('X-Fluent-Signature');
+    const body = await req.text();
+
+    const result = await parseWebhookRequest({
+      body,
+      signature,
+      secret: Deno.env.get('FLUENT_WEBHOOK_SECRET')
+    });
+
+    if (!result.valid) {
+      return new Response('Unauthorized', { status: 401 });
+    }
+
+    await processEvent(result.payload);
+    return new Response('OK', { status: 200 });
+  }
+});
+```
+
+---
+
+## Error Handling
+
+### Common Errors
+
+```typescript
+const result = await parseWebhookRequest({ body, signature, secret });
+
+if (!result.valid) {
+  switch (result.error) {
+    case 'Missing signature':
+      // No X-Fluent-Signature header
+      return new Response('Missing signature header', { status: 400 });
+
+    case 'Invalid signature format':
+      // Malformed signature (not t=...,v1=...)
+      return new Response('Bad signature format', { status: 400 });
+
+    case 'Timestamp too old':
+      // Request older than tolerance window
+      return new Response('Request expired', { status: 401 });
+
+    case 'Signature mismatch':
+      // HMAC doesn't match (wrong secret or tampered body)
+      return new Response('Unauthorized', { status: 401 });
+
+    default:
+      return new Response('Validation failed', { status: 401 });
+  }
+}
+```
+
+### Logging Validation Failures
+
+```typescript
+const result = await parseWebhookRequest({ body, signature, secret });
+
+if (!result.valid) {
+  // Log for security monitoring
+  log.warn('Webhook validation failed', {
+    error: result.error,
+    signature: signature.substring(0, 20) + '...',  // Truncate for logs
+    bodyLength: body.length,
+    timestamp: result.timestamp,
+    ip: req.headers.get('X-Forwarded-For')
+  });
+
+  return new Response('Unauthorized', { status: 401 });
+}
+```
+
+---
+
+## Common Patterns
+
+### Pattern 1: Idempotent Processing
+
+```typescript
+const result = await parseWebhookRequest({ body, signature, secret });
+if (!result.valid) return unauthorized();
+
+const eventId = result.payload.id;
+
+// Check if already processed
+if (await stateService.isEventProcessed(eventId)) {
+  return new Response('Already processed', { status: 200 });
+}
+
+// Process event
+await processEvent(result.payload);
+
+// Mark as processed
+await stateService.markEventProcessed(eventId);
+
+return new Response('OK', { status: 200 });
+```
+
+### Pattern 2: Event Type Routing
+
+```typescript
+const result = await parseWebhookRequest({ body, signature, secret });
+if (!result.valid) return unauthorized();
+
+const { eventName, entity } = result.payload;
+
+switch (eventName) {
+  case 'ORDER.CREATED':
+    await handleOrderCreated(entity);
+    break;
+
+  case 'FULFILMENT.UPDATED':
+    await handleFulfilmentUpdated(entity);
+    break;
+
+  case 'INVENTORY.ADJUSTED':
+    await handleInventoryAdjusted(entity);
+    break;
+
+  default:
+    console.log(`Unhandled event: ${eventName}`);
+}
+
+return new Response('OK', { status: 200 });
+```
+
+### Pattern 3: Async Processing
+
+```typescript
+const result = await parseWebhookRequest({ body, signature, secret });
+if (!result.valid) return unauthorized();
+
+// Acknowledge webhook immediately
+queueForProcessing(result.payload);
+
+return new Response('Accepted', { status: 202 });
+
+// Process asynchronously
+async function queueForProcessing(payload) {
+  await messageQueue.publish('fluent-events', payload);
+}
+```
+
+---
+
+## Troubleshooting
+
+### Issue 1: Always Getting "Signature mismatch"
+
+**Causes:**
+- Wrong webhook secret
+- Body modified before validation
+- JSON parsing before validation
+
+**Solutions:**
+```typescript
+// ✅ Use raw body for validation
+app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
+  const result = await parseWebhookRequest({
+    body: req.body,  // Raw buffer, not parsed JSON
+    signature: req.headers['x-fluent-signature'],
+    secret: process.env.FLUENT_WEBHOOK_SECRET
+  });
+});
+
+// ❌ WRONG: Parse JSON first
+app.post('/webhook', express.json(), async (req, res) => {
+  // Body already parsed - signature will fail!
+});
+```
+
+### Issue 2: "Timestamp too old" Errors
+
+**Causes:**
+- Server clock skew
+- Network delays
+- Tolerance too strict
+
+**Solutions:**
+```typescript
+// ✅ Increase tolerance if needed
+const result = await parseWebhookRequest({
+  body,
+  signature,
+  secret,
+  toleranceMs: 600000  // 10 minutes for slow networks
+});
+```
+
+### Issue 3: Missing Signature Header
+
+**Cause:** Header not forwarded by proxy/load balancer
+
+**Solution:**
+```typescript
+// Check different header names
+const signature =
+  req.headers.get('X-Fluent-Signature') ||
+  req.headers.get('x-fluent-signature') ||
+  req.headers.get('X-Fluent-Signature'.toLowerCase());
+```
+
+---
+
+## See Also
+
+**Related Modules:**
+- [Module 01: Client API](./api-reference-01-client-api.md) - FluentClient creation
+- [Module 11: Error Handling](./api-reference-11-error-handling.md) - Error strategies
+
+**Complete Guides:**
+- [Webhook Validation Guide](../../webhook-validation/webhook-validation-readme.md) - Full webhook validation series
+- [Versori Webhook Patterns](../../../04-REFERENCE/platforms/versori/platforms-versori-webhook-connection-security.md)
+
+**Templates:**
+- [Generic XML Order Webhook](../../../01-TEMPLATES/versori/webhooks/template-webhook-generic-xml-order.md)
+- [ASN Purchase Order Webhook](../../../01-TEMPLATES/versori/webhooks/template-webhook-asn-purchase-order.md)
+
+---
+
+**Navigation:**
+- [Back to Module List](./readme.md)
+- [Previous: Module 08 - Pagination](./api-reference-08-pagination.md)
+- [Next: Module 10 - Extraction](./api-reference-10-extraction.md)