npm - @fluentcommerce/fc-connect-sdk - Versions diffs - 0.1.54 → 0.1.55 - Mend

@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (475) hide show

package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-06-error-handling.md CHANGED Viewed

@@ -1,611 +1,611 @@
-# Module 6: Error Handling
-**Level:** Intermediate
-**Estimated Time:** 25 minutes
-## Overview
-This module covers comprehensive error handling for webhook validation, including validation result structures, common error scenarios, debugging techniques, and recovery strategies.
-## Learning Objectives
-By the end of this module, you will:
-- Understand WebhookValidationResult structure
-- Handle common validation error scenarios
-- Debug validation failures effectively
-- Implement logging and monitoring
-- Build resilient webhook handlers
----
-## Validation Result Structure
-### WebhookValidationResult Interface
-```typescript
-interface WebhookValidationResult {
-  /**
-   * Whether the webhook signature is valid
-   */
-  isValid: boolean;
-  /**
-   * Algorithm used for validation
-   */
-  algorithm: SignatureAlgorithm;
-  /**
-   * Error message if validation failed
-   * undefined if isValid === true
-   */
-  error?: string;
-  /**
-   * Timestamp when validation occurred
-   */
-  timestamp: Date;
-}
-```
-### Success Result
-```typescript
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (result.isValid) {
-  console.log({
-    isValid: true,
-    algorithm: 'SHA512withRSA',  // or 'MD5withRSA'
-    timestamp: '2025-01-14T10:30:00.000Z',
-    error: undefined
-  });
-}
-```
-### Failure Result
-```typescript
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (!result.isValid) {
-  console.log({
-    isValid: false,
-    algorithm: 'SHA512withRSA',  // Attempted algorithm
-    error: 'Signature verification failed',
-    timestamp: '2025-01-14T10:30:00.000Z'
-  });
-}
-```
----
-## Common Error Scenarios
-### Error 1: Missing Signature Header
-```typescript
-// Webhook request without signature header
-const headers = {
-  'content-type': 'application/json'
-  // No 'fluent-signature' or 'flex.signature'
-};
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-// Result:
-{
-  isValid: false,
-  algorithm: 'SHA512withRSA',  // Default algorithm
-  error: 'No signature header found',
-  timestamp: Date
-}
-```
-**Causes**:
-- Webhook not from Fluent Commerce Rubix
-- Misconfigured Rubix workflow
-- Testing with manually crafted requests
-**Solution**:
-```typescript
-if (!result.isValid && result.error?.includes('No signature header')) {
-  logger.error('Webhook missing signature - not from Fluent Commerce');
-  return { statusCode: 400, body: 'Missing signature header' };
-}
-```
-### Error 2: Invalid Signature
-```typescript
-// Signature doesn't match payload
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-// Result:
-{
-  isValid: false,
-  algorithm: 'SHA512withRSA',
-  error: 'Signature verification failed',
-  timestamp: Date
-}
-```
-**Causes**:
-- Wrong public key (production key used for sandbox webhook)
-- Body was modified before validation
-- Signature header corrupted in transit
-- Webhook not from Fluent Commerce
-**Solution**:
-```typescript
-if (!result.isValid && result.error?.includes('verification failed')) {
-  logger.warn('Invalid signature detected', {
-    error: result.error,
-    algorithm: result.algorithm,
-    hasSignature: !!headers['fluent-signature'] || !!headers['flex.signature'],
-    bodyLength: rawBody.length
-  });
-  return { statusCode: 401, body: 'Invalid signature' };
-}
-```
-### Error 3: Missing Public Key
-```typescript
-const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-if (!publicKey) {
-  // This will throw error before validation
-  throw new Error('FLUENT_WEBHOOK_PUBLIC_KEY not configured');
-}
-```
-**Causes**:
-- Environment variable not set
-- Configuration not loaded
-- Versori variable not defined
-**Solution**:
-```typescript
-const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-if (!publicKey) {
-  logger.error('Missing public key configuration');
-  return { statusCode: 500, body: 'Server configuration error' };
-}
-```
-### Error 4: Invalid Public Key Format
-```typescript
-const result = await validator.validateWebhook(rawBody, headers, invalidKey);
-// May throw error:
-// "Invalid public key format"
-```
-**Causes**:
-- Truncated public key
-- Wrong key format (not PEM or base64)
-- Corrupted key in storage
-**Solution**:
-```typescript
-try {
-  const result = await validator.validateWebhook(rawBody, headers, publicKey);
-} catch (error) {
-  if (error.message.includes('Invalid public key')) {
-    logger.error('Public key format error', { publicKeyPrefix: publicKey.substring(0, 30) });
-    return { statusCode: 500, body: 'Configuration error' };
-  }
-  throw error;
-}
-```
-### Error 5: Body Modified Before Validation
-```typescript
-// ❌ WRONG - Body was parsed and re-stringified
-const data = JSON.parse(rawBody);
-const modifiedBody = JSON.stringify(data);  // May change whitespace, key order
-const result = await validator.validateWebhook(modifiedBody, headers, publicKey);
-// isValid: false, error: 'Signature verification failed'
-```
-**Causes**:
-- JSON parsed before validation
-- Whitespace trimmed
-- Character encoding changed
-**Solution**:
-```typescript
-// ✅ CORRECT - Use original raw body
-const rawBody = await request.text();  // Original bytes
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (result.isValid) {
-  const data = JSON.parse(rawBody);  // Parse after validation
-}
-```
----
-## Debugging Validation Failures
-### Debug Pattern 1: Log All Validation Attempts
-```typescript
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-logger.info('Validation attempt', {
-  isValid: result.isValid,
-  algorithm: result.algorithm,
-  error: result.error,
-  timestamp: result.timestamp,
-  bodyLength: rawBody.length,
-  headers: Object.keys(headers),
-  hasFluentSig: !!headers['fluent-signature'],
-  hasFlexSig: !!headers['flex.signature'],
-  publicKeyPrefix: publicKey.substring(0, 30)
-});
-```
-### Debug Pattern 2: Compare Algorithms
-```typescript
-// Try both algorithms to see which should work
-const sha512Result = await validator.validateWebhookSignature(
-  rawBody,
-  headers['fluent-signature'],
-  publicKey,
-  SignatureAlgorithm.SHA512_WITH_RSA
-);
-const md5Result = await validator.validateWebhookSignature(
-  rawBody,
-  headers['flex.signature'],
-  publicKey,
-  SignatureAlgorithm.MD5_WITH_RSA
-);
-console.log('SHA512 validation:', sha512Result);
-console.log('MD5 validation:', md5Result);
-```
-### Debug Pattern 3: Validate Key Format
-```typescript
-function validatePublicKeyFormat(publicKey: string): boolean {
-  // Check for PEM format
-  if (publicKey.includes('-----BEGIN PUBLIC KEY-----')) {
-    return publicKey.includes('-----END PUBLIC KEY-----');
-  }
-  // Check for base64 format
-  const base64Regex = /^[A-Za-z0-9+/]+=*$/;
-  return base64Regex.test(publicKey.trim());
-}
-const isValidFormat = validatePublicKeyFormat(publicKey);
-if (!isValidFormat) {
-  logger.error('Invalid public key format detected');
-}
-```
-### Debug Pattern 4: Check Environment Mismatch
-```typescript
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (!result.isValid) {
-  logger.warn('Validation failed - check environment mismatch', {
-    error: result.error,
-    currentEnv: process.env.NODE_ENV,
-    fluentEnv: process.env.FLUENT_ENV,
-    keySource: 'Check if production key used for sandbox webhook'
-  });
-}
-```
----
-## Logging and Monitoring
-### Security Event Logging
-```typescript
-async function validateAndLogWebhook(
-  rawBody: string,
-  headers: Record<string, string>,
-  publicKey: string,
-  logger: Logger
-): Promise<WebhookValidationResult> {
-  const result = await validator.validateWebhook(rawBody, headers, publicKey);
-  if (!result.isValid) {
-    // Log security event
-    logger.warn('Webhook validation failed', {
-      severity: 'SECURITY',
-      error: result.error,
-      algorithm: result.algorithm,
-      timestamp: result.timestamp.toISOString(),
-      sourceIp: headers['x-forwarded-for'] || headers['x-real-ip'] || 'unknown',
-      userAgent: headers['user-agent'] || 'unknown',
-      signaturePresent: !!headers['fluent-signature'] || !!headers['flex.signature']
-    });
-    // Optionally alert security team
-    if (await shouldAlertSecurity(result.error)) {
-      await alertSecurityTeam({
-        event: 'Invalid webhook signature',
-        details: result.error,
-        timestamp: result.timestamp
-      });
-    }
-  }
-  return result;
-}
-```
-### Metrics Collection
-```typescript
-interface ValidationMetrics {
-  totalAttempts: number;
-  successCount: number;
-  failureCount: number;
-  errorTypes: Record<string, number>;
-  algorithms: Record<string, number>;
-}
-const metrics: ValidationMetrics = {
-  totalAttempts: 0,
-  successCount: 0,
-  failureCount: 0,
-  errorTypes: {},
-  algorithms: {}
-};
-async function validateWithMetrics(
-  rawBody: string,
-  headers: Record<string, string>,
-  publicKey: string
-): Promise<WebhookValidationResult> {
-  const result = await validator.validateWebhook(rawBody, headers, publicKey);
-  metrics.totalAttempts++;
-  if (result.isValid) {
-    metrics.successCount++;
-  } else {
-    metrics.failureCount++;
-    const errorType = result.error || 'unknown';
-    metrics.errorTypes[errorType] = (metrics.errorTypes[errorType] || 0) + 1;
-  }
-  metrics.algorithms[result.algorithm] = (metrics.algorithms[result.algorithm] || 0) + 1;
-  return result;
-}
-// Report metrics periodically
-setInterval(() => {
-  console.log('Webhook validation metrics:', metrics);
-}, 60000);  // Every minute
-```
----
-## Error Recovery Strategies
-### Strategy 1: Retry with Fallback Algorithm
-```typescript
-async function validateWithFallback(
-  rawBody: string,
-  headers: Record<string, string>,
-  publicKey: string
-): Promise<WebhookValidationResult> {
-  // Try auto-detection first
-  let result = await validator.validateWebhook(rawBody, headers, publicKey);
-  if (!result.isValid && result.error?.includes('No signature header')) {
-    // Try manual algorithm selection
-    if (headers['fluent-signature']) {
-      result = await validator.validateWebhookSignature(
-        rawBody,
-        headers['fluent-signature'],
-        publicKey,
-        SignatureAlgorithm.SHA512_WITH_RSA
-      );
-    } else if (headers['flex.signature']) {
-      result = await validator.validateWebhookSignature(
-        rawBody,
-        headers['flex.signature'],
-        publicKey,
-        SignatureAlgorithm.MD5_WITH_RSA
-      );
-    }
-  }
-  return result;
-}
-```
-### Strategy 2: Environment-Specific Key Selection
-```typescript
-async function validateWithEnvironmentKey(
-  rawBody: string,
-  headers: Record<string, string>
-): Promise<WebhookValidationResult> {
-  // Detect environment from webhook metadata
-  const webhookData = JSON.parse(rawBody);
-  const sourceEnv = webhookData.environment || 'production';
-  // Select appropriate public key
-  const publicKey = sourceEnv === 'production'
-    ? process.env.FLUENT_WEBHOOK_PUBLIC_KEY_PROD!
-    : process.env.FLUENT_WEBHOOK_PUBLIC_KEY_SANDBOX!;
-  return await validator.validateWebhook(rawBody, headers, publicKey);
-}
-```
-### Strategy 3: Graceful Degradation
-```typescript
-async function validateWithGracefulDegradation(
-  rawBody: string,
-  headers: Record<string, string>,
-  publicKey: string
-): Promise<{ isValid: boolean; degraded: boolean }> {
-  try {
-    const result = await validator.validateWebhook(rawBody, headers, publicKey);
-    if (result.isValid) {
-      return { isValid: true, degraded: false };
-    }
-    // In development, allow processing without signature
-    if (process.env.NODE_ENV === 'development') {
-      logger.warn('Allowing invalid webhook in development mode');
-      return { isValid: true, degraded: true };
-    }
-    return { isValid: false, degraded: false };
-  } catch (error) {
-    logger.error('Validation error', { error });
-    return { isValid: false, degraded: false };
-  }
-}
-```
----
-## Complete Error Handling Example
-```typescript
-import {
-  WebhookValidationService,
-  WebhookValidationFactory,
-  WebhookValidationResult,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-async function handleWebhookWithComprehensiveErrorHandling(
-  rawBody: string,
-  headers: Record<string, string>
-): Promise<{ statusCode: number; body: any }> {
-  const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-  const validator = WebhookValidationFactory.createProduction(logger);
-  try {
-    // 1. Check public key
-    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-    if (!publicKey) {
-      logger.error('Missing FLUENT_WEBHOOK_PUBLIC_KEY environment variable');
-      return {
-        statusCode: 500,
-        body: { error: 'Server configuration error' }
-      };
-    }
-    // 2. Validate webhook
-    const result: WebhookValidationResult = await validator.validateWebhook(
-      rawBody,
-      headers,
-      publicKey
-    );
-    // 3. Handle validation failure
-    if (!result.isValid) {
-      logger.warn('Webhook validation failed', {
-        error: result.error,
-        algorithm: result.algorithm,
-        timestamp: result.timestamp.toISOString(),
-        headers: Object.keys(headers)
-      });
-      // Specific error handling
-      if (result.error?.includes('No signature header')) {
-        return {
-          statusCode: 400,
-          body: { error: 'Missing signature header' }
-        };
-      }
-      if (result.error?.includes('verification failed')) {
-        // Log security event
-        logger.error('SECURITY: Invalid webhook signature detected', {
-          sourceIp: headers['x-forwarded-for'] || 'unknown'
-        });
-        return {
-          statusCode: 401,
-          body: { error: 'Invalid signature' }
-        };
-      }
-      // Generic validation failure
-      return {
-        statusCode: 401,
-        body: { error: 'Validation failed', details: result.error }
-      };
-    }
-    // 4. Process valid webhook
-    logger.info('Webhook validated successfully', {
-      algorithm: result.algorithm,
-      timestamp: result.timestamp.toISOString()
-    });
-    const data = JSON.parse(rawBody);
-    await processWebhook(data);
-    return {
-      statusCode: 200,
-      body: { success: true, eventId: data.eventId }
-    };
-  } catch (error: any) {
-    logger.error('Unexpected error processing webhook', { error: error.message });
-    return {
-      statusCode: 500,
-      body: { error: 'Internal server error' }
-    };
-  }
-}
-async function processWebhook(data: any): Promise<void> {
-  console.log('Processing webhook:', data);
-}
-```
----
-## Key Takeaways
-- **Check isValid first** - always validate before processing
-- **Log validation failures** - track security events and patterns
-- **Return appropriate HTTP codes** - 400 for missing signature, 401 for invalid signature, 500 for config errors
-- **Use structured logging** - include error details, algorithm, timestamp
-- **Monitor metrics** - track success/failure rates over time
-- **Handle environment mismatches** - use correct public key for environment
-- **Never log raw signatures** - security risk
----
-## Next Steps
-Continue to [Module 7: API Reference](../../auto-pagination/modules/auto-pagination-07-api-reference.md) for complete API documentation and TypeScript type definitions.
----
-## Further Reading
-- [Module 5: Configuration](./webhook-validation-05-configuration.md) - Configuration options
-- [Module 2: Quick Start](../../auto-pagination/modules/auto-pagination-02-quick-start.md) - Basic usage patterns
-- [Quick Reference](../../advanced-services/advanced-services-quick-reference.md) - One-page cheat sheet
+# Module 6: Error Handling
+**Level:** Intermediate
+**Estimated Time:** 25 minutes
+## Overview
+This module covers comprehensive error handling for webhook validation, including validation result structures, common error scenarios, debugging techniques, and recovery strategies.
+## Learning Objectives
+By the end of this module, you will:
+- Understand WebhookValidationResult structure
+- Handle common validation error scenarios
+- Debug validation failures effectively
+- Implement logging and monitoring
+- Build resilient webhook handlers
+---
+## Validation Result Structure
+### WebhookValidationResult Interface
+```typescript
+interface WebhookValidationResult {
+  /**
+   * Whether the webhook signature is valid
+   */
+  isValid: boolean;
+  /**
+   * Algorithm used for validation
+   */
+  algorithm: SignatureAlgorithm;
+  /**
+   * Error message if validation failed
+   * undefined if isValid === true
+   */
+  error?: string;
+  /**
+   * Timestamp when validation occurred
+   */
+  timestamp: Date;
+}
+```
+### Success Result
+```typescript
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (result.isValid) {
+  console.log({
+    isValid: true,
+    algorithm: 'SHA512withRSA',  // or 'MD5withRSA'
+    timestamp: '2025-01-14T10:30:00.000Z',
+    error: undefined
+  });
+}
+```
+### Failure Result
+```typescript
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (!result.isValid) {
+  console.log({
+    isValid: false,
+    algorithm: 'SHA512withRSA',  // Attempted algorithm
+    error: 'Signature verification failed',
+    timestamp: '2025-01-14T10:30:00.000Z'
+  });
+}
+```
+---
+## Common Error Scenarios
+### Error 1: Missing Signature Header
+```typescript
+// Webhook request without signature header
+const headers = {
+  'content-type': 'application/json'
+  // No 'fluent-signature' or 'flex.signature'
+};
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+// Result:
+{
+  isValid: false,
+  algorithm: 'SHA512withRSA',  // Default algorithm
+  error: 'No signature header found',
+  timestamp: Date
+}
+```
+**Causes**:
+- Webhook not from Fluent Commerce Rubix
+- Misconfigured Rubix workflow
+- Testing with manually crafted requests
+**Solution**:
+```typescript
+if (!result.isValid && result.error?.includes('No signature header')) {
+  logger.error('Webhook missing signature - not from Fluent Commerce');
+  return { statusCode: 400, body: 'Missing signature header' };
+}
+```
+### Error 2: Invalid Signature
+```typescript
+// Signature doesn't match payload
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+// Result:
+{
+  isValid: false,
+  algorithm: 'SHA512withRSA',
+  error: 'Signature verification failed',
+  timestamp: Date
+}
+```
+**Causes**:
+- Wrong public key (production key used for sandbox webhook)
+- Body was modified before validation
+- Signature header corrupted in transit
+- Webhook not from Fluent Commerce
+**Solution**:
+```typescript
+if (!result.isValid && result.error?.includes('verification failed')) {
+  logger.warn('Invalid signature detected', {
+    error: result.error,
+    algorithm: result.algorithm,
+    hasSignature: !!headers['fluent-signature'] || !!headers['flex.signature'],
+    bodyLength: rawBody.length
+  });
+  return { statusCode: 401, body: 'Invalid signature' };
+}
+```
+### Error 3: Missing Public Key
+```typescript
+const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+if (!publicKey) {
+  // This will throw error before validation
+  throw new Error('FLUENT_WEBHOOK_PUBLIC_KEY not configured');
+}
+```
+**Causes**:
+- Environment variable not set
+- Configuration not loaded
+- Versori variable not defined
+**Solution**:
+```typescript
+const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+if (!publicKey) {
+  logger.error('Missing public key configuration');
+  return { statusCode: 500, body: 'Server configuration error' };
+}
+```
+### Error 4: Invalid Public Key Format
+```typescript
+const result = await validator.validateWebhook(rawBody, headers, invalidKey);
+// May throw error:
+// "Invalid public key format"
+```
+**Causes**:
+- Truncated public key
+- Wrong key format (not PEM or base64)
+- Corrupted key in storage
+**Solution**:
+```typescript
+try {
+  const result = await validator.validateWebhook(rawBody, headers, publicKey);
+} catch (error) {
+  if (error.message.includes('Invalid public key')) {
+    logger.error('Public key format error', { publicKeyPrefix: publicKey.substring(0, 30) });
+    return { statusCode: 500, body: 'Configuration error' };
+  }
+  throw error;
+}
+```
+### Error 5: Body Modified Before Validation
+```typescript
+// ❌ WRONG - Body was parsed and re-stringified
+const data = JSON.parse(rawBody);
+const modifiedBody = JSON.stringify(data);  // May change whitespace, key order
+const result = await validator.validateWebhook(modifiedBody, headers, publicKey);
+// isValid: false, error: 'Signature verification failed'
+```
+**Causes**:
+- JSON parsed before validation
+- Whitespace trimmed
+- Character encoding changed
+**Solution**:
+```typescript
+// ✅ CORRECT - Use original raw body
+const rawBody = await request.text();  // Original bytes
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (result.isValid) {
+  const data = JSON.parse(rawBody);  // Parse after validation
+}
+```
+---
+## Debugging Validation Failures
+### Debug Pattern 1: Log All Validation Attempts
+```typescript
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+logger.info('Validation attempt', {
+  isValid: result.isValid,
+  algorithm: result.algorithm,
+  error: result.error,
+  timestamp: result.timestamp,
+  bodyLength: rawBody.length,
+  headers: Object.keys(headers),
+  hasFluentSig: !!headers['fluent-signature'],
+  hasFlexSig: !!headers['flex.signature'],
+  publicKeyPrefix: publicKey.substring(0, 30)
+});
+```
+### Debug Pattern 2: Compare Algorithms
+```typescript
+// Try both algorithms to see which should work
+const sha512Result = await validator.validateWebhookSignature(
+  rawBody,
+  headers['fluent-signature'],
+  publicKey,
+  SignatureAlgorithm.SHA512_WITH_RSA
+);
+const md5Result = await validator.validateWebhookSignature(
+  rawBody,
+  headers['flex.signature'],
+  publicKey,
+  SignatureAlgorithm.MD5_WITH_RSA
+);
+console.log('SHA512 validation:', sha512Result);
+console.log('MD5 validation:', md5Result);
+```
+### Debug Pattern 3: Validate Key Format
+```typescript
+function validatePublicKeyFormat(publicKey: string): boolean {
+  // Check for PEM format
+  if (publicKey.includes('-----BEGIN PUBLIC KEY-----')) {
+    return publicKey.includes('-----END PUBLIC KEY-----');
+  }
+  // Check for base64 format
+  const base64Regex = /^[A-Za-z0-9+/]+=*$/;
+  return base64Regex.test(publicKey.trim());
+}
+const isValidFormat = validatePublicKeyFormat(publicKey);
+if (!isValidFormat) {
+  logger.error('Invalid public key format detected');
+}
+```
+### Debug Pattern 4: Check Environment Mismatch
+```typescript
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (!result.isValid) {
+  logger.warn('Validation failed - check environment mismatch', {
+    error: result.error,
+    currentEnv: process.env.NODE_ENV,
+    fluentEnv: process.env.FLUENT_ENV,
+    keySource: 'Check if production key used for sandbox webhook'
+  });
+}
+```
+---
+## Logging and Monitoring
+### Security Event Logging
+```typescript
+async function validateAndLogWebhook(
+  rawBody: string,
+  headers: Record<string, string>,
+  publicKey: string,
+  logger: Logger
+): Promise<WebhookValidationResult> {
+  const result = await validator.validateWebhook(rawBody, headers, publicKey);
+  if (!result.isValid) {
+    // Log security event
+    logger.warn('Webhook validation failed', {
+      severity: 'SECURITY',
+      error: result.error,
+      algorithm: result.algorithm,
+      timestamp: result.timestamp.toISOString(),
+      sourceIp: headers['x-forwarded-for'] || headers['x-real-ip'] || 'unknown',
+      userAgent: headers['user-agent'] || 'unknown',
+      signaturePresent: !!headers['fluent-signature'] || !!headers['flex.signature']
+    });
+    // Optionally alert security team
+    if (await shouldAlertSecurity(result.error)) {
+      await alertSecurityTeam({
+        event: 'Invalid webhook signature',
+        details: result.error,
+        timestamp: result.timestamp
+      });
+    }
+  }
+  return result;
+}
+```
+### Metrics Collection
+```typescript
+interface ValidationMetrics {
+  totalAttempts: number;
+  successCount: number;
+  failureCount: number;
+  errorTypes: Record<string, number>;
+  algorithms: Record<string, number>;
+}
+const metrics: ValidationMetrics = {
+  totalAttempts: 0,
+  successCount: 0,
+  failureCount: 0,
+  errorTypes: {},
+  algorithms: {}
+};
+async function validateWithMetrics(
+  rawBody: string,
+  headers: Record<string, string>,
+  publicKey: string
+): Promise<WebhookValidationResult> {
+  const result = await validator.validateWebhook(rawBody, headers, publicKey);
+  metrics.totalAttempts++;
+  if (result.isValid) {
+    metrics.successCount++;
+  } else {
+    metrics.failureCount++;
+    const errorType = result.error || 'unknown';
+    metrics.errorTypes[errorType] = (metrics.errorTypes[errorType] || 0) + 1;
+  }
+  metrics.algorithms[result.algorithm] = (metrics.algorithms[result.algorithm] || 0) + 1;
+  return result;
+}
+// Report metrics periodically
+setInterval(() => {
+  console.log('Webhook validation metrics:', metrics);
+}, 60000);  // Every minute
+```
+---
+## Error Recovery Strategies
+### Strategy 1: Retry with Fallback Algorithm
+```typescript
+async function validateWithFallback(
+  rawBody: string,
+  headers: Record<string, string>,
+  publicKey: string
+): Promise<WebhookValidationResult> {
+  // Try auto-detection first
+  let result = await validator.validateWebhook(rawBody, headers, publicKey);
+  if (!result.isValid && result.error?.includes('No signature header')) {
+    // Try manual algorithm selection
+    if (headers['fluent-signature']) {
+      result = await validator.validateWebhookSignature(
+        rawBody,
+        headers['fluent-signature'],
+        publicKey,
+        SignatureAlgorithm.SHA512_WITH_RSA
+      );
+    } else if (headers['flex.signature']) {
+      result = await validator.validateWebhookSignature(
+        rawBody,
+        headers['flex.signature'],
+        publicKey,
+        SignatureAlgorithm.MD5_WITH_RSA
+      );
+    }
+  }
+  return result;
+}
+```
+### Strategy 2: Environment-Specific Key Selection
+```typescript
+async function validateWithEnvironmentKey(
+  rawBody: string,
+  headers: Record<string, string>
+): Promise<WebhookValidationResult> {
+  // Detect environment from webhook metadata
+  const webhookData = JSON.parse(rawBody);
+  const sourceEnv = webhookData.environment || 'production';
+  // Select appropriate public key
+  const publicKey = sourceEnv === 'production'
+    ? process.env.FLUENT_WEBHOOK_PUBLIC_KEY_PROD!
+    : process.env.FLUENT_WEBHOOK_PUBLIC_KEY_SANDBOX!;
+  return await validator.validateWebhook(rawBody, headers, publicKey);
+}
+```
+### Strategy 3: Graceful Degradation
+```typescript
+async function validateWithGracefulDegradation(
+  rawBody: string,
+  headers: Record<string, string>,
+  publicKey: string
+): Promise<{ isValid: boolean; degraded: boolean }> {
+  try {
+    const result = await validator.validateWebhook(rawBody, headers, publicKey);
+    if (result.isValid) {
+      return { isValid: true, degraded: false };
+    }
+    // In development, allow processing without signature
+    if (process.env.NODE_ENV === 'development') {
+      logger.warn('Allowing invalid webhook in development mode');
+      return { isValid: true, degraded: true };
+    }
+    return { isValid: false, degraded: false };
+  } catch (error) {
+    logger.error('Validation error', { error });
+    return { isValid: false, degraded: false };
+  }
+}
+```
+---
+## Complete Error Handling Example
+```typescript
+import {
+  WebhookValidationService,
+  WebhookValidationFactory,
+  WebhookValidationResult,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+async function handleWebhookWithComprehensiveErrorHandling(
+  rawBody: string,
+  headers: Record<string, string>
+): Promise<{ statusCode: number; body: any }> {
+  const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+  const validator = WebhookValidationFactory.createProduction(logger);
+  try {
+    // 1. Check public key
+    const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+    if (!publicKey) {
+      logger.error('Missing FLUENT_WEBHOOK_PUBLIC_KEY environment variable');
+      return {
+        statusCode: 500,
+        body: { error: 'Server configuration error' }
+      };
+    }
+    // 2. Validate webhook
+    const result: WebhookValidationResult = await validator.validateWebhook(
+      rawBody,
+      headers,
+      publicKey
+    );
+    // 3. Handle validation failure
+    if (!result.isValid) {
+      logger.warn('Webhook validation failed', {
+        error: result.error,
+        algorithm: result.algorithm,
+        timestamp: result.timestamp.toISOString(),
+        headers: Object.keys(headers)
+      });
+      // Specific error handling
+      if (result.error?.includes('No signature header')) {
+        return {
+          statusCode: 400,
+          body: { error: 'Missing signature header' }
+        };
+      }
+      if (result.error?.includes('verification failed')) {
+        // Log security event
+        logger.error('SECURITY: Invalid webhook signature detected', {
+          sourceIp: headers['x-forwarded-for'] || 'unknown'
+        });
+        return {
+          statusCode: 401,
+          body: { error: 'Invalid signature' }
+        };
+      }
+      // Generic validation failure
+      return {
+        statusCode: 401,
+        body: { error: 'Validation failed', details: result.error }
+      };
+    }
+    // 4. Process valid webhook
+    logger.info('Webhook validated successfully', {
+      algorithm: result.algorithm,
+      timestamp: result.timestamp.toISOString()
+    });
+    const data = JSON.parse(rawBody);
+    await processWebhook(data);
+    return {
+      statusCode: 200,
+      body: { success: true, eventId: data.eventId }
+    };
+  } catch (error: any) {
+    logger.error('Unexpected error processing webhook', { error: error.message });
+    return {
+      statusCode: 500,
+      body: { error: 'Internal server error' }
+    };
+  }
+}
+async function processWebhook(data: any): Promise<void> {
+  console.log('Processing webhook:', data);
+}
+```
+---
+## Key Takeaways
+- **Check isValid first** - always validate before processing
+- **Log validation failures** - track security events and patterns
+- **Return appropriate HTTP codes** - 400 for missing signature, 401 for invalid signature, 500 for config errors
+- **Use structured logging** - include error details, algorithm, timestamp
+- **Monitor metrics** - track success/failure rates over time
+- **Handle environment mismatches** - use correct public key for environment
+- **Never log raw signatures** - security risk
+---
+## Next Steps
+Continue to [Module 7: API Reference](../../auto-pagination/modules/auto-pagination-07-api-reference.md) for complete API documentation and TypeScript type definitions.
+---
+## Further Reading
+- [Module 5: Configuration](./webhook-validation-05-configuration.md) - Configuration options
+- [Module 2: Quick Start](../../auto-pagination/modules/auto-pagination-02-quick-start.md) - Basic usage patterns
+- [Quick Reference](../../advanced-services/advanced-services-quick-reference.md) - One-page cheat sheet