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-05-configuration.md CHANGED Viewed

@@ -1,535 +1,535 @@
-# Module 5: Configuration
-**Level:** Intermediate
-**Estimated Time:** 20 minutes
-## Overview
-This module covers all configuration options for WebhookValidationService, including factory methods for common scenarios, strict vs lenient validation, and custom configurations.
-## Learning Objectives
-By the end of this module, you will:
-- Understand all configuration options
-- Use factory methods for common scenarios
-- Configure strict vs lenient validation
-- Set default algorithms
-- Create custom validator configurations
----
-## Configuration Options
-### WebhookValidationConfig Interface
-```typescript
-interface WebhookValidationConfig {
-  /**
-   * Throw errors on validation failure instead of returning result
-   * Default: false
-   */
-  strictValidation?: boolean;
-  /**
-   * Default algorithm to use if not auto-detected
-   * Default: SignatureAlgorithm.SHA512_WITH_RSA
-   */
-  algorithm?: SignatureAlgorithm;
-}
-```
-### Basic Configuration
-```typescript
-import {
-  WebhookValidationService,
-  SignatureAlgorithm,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-// Minimal configuration (uses defaults)
-const validator1 = new WebhookValidationService({}, logger);
-// With strict validation
-const validator2 = new WebhookValidationService({
-  strictValidation: true
-}, logger);
-// With default algorithm
-const validator3 = new WebhookValidationService({
-  algorithm: SignatureAlgorithm.MD5_WITH_RSA
-}, logger);
-// Complete configuration
-const validator4 = new WebhookValidationService({
-  strictValidation: true,
-  algorithm: SignatureAlgorithm.SHA512_WITH_RSA
-}, logger);
-```
----
-## Strict vs Lenient Validation
-### Lenient Validation (Default)
-**Returns validation result** - doesn't throw errors:
-```typescript
-const validator = new WebhookValidationService({
-  strictValidation: false  // or omit (default)
-}, logger);
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (!result.isValid) {
-  // Handle validation failure gracefully
-  console.error('Validation failed:', result.error);
-  return { statusCode: 401, body: 'Invalid signature' };
-}
-// Continue with valid webhook
-```
-**Use when**:
-- You want to handle validation failures gracefully
-- You need custom error handling logic
-- You want to log additional context before failing
-- You're building a public API with detailed error responses
-### Strict Validation
-**Throws errors** on validation failure:
-```typescript
-const validator = new WebhookValidationService({
-  strictValidation: true
-}, logger);
-try {
-  const result = await validator.validateWebhook(rawBody, headers, publicKey);
-  // If we reach here, validation succeeded
-  console.log('Valid webhook using:', result.algorithm);
-} catch (error) {
-  // Validation failed - error thrown
-  console.error('Validation error:', error.message);
-  return { statusCode: 401, body: 'Invalid signature' };
-}
-```
-**Use when**:
-- You want fail-fast behavior
-- Validation failures should be treated as exceptions
-- You're using try/catch for error handling
-- You want cleaner code flow (no if/else checks)
-### Comparison
-```typescript
-// LENIENT - Check result
-const result = await validator.validateWebhook(...);
-if (!result.isValid) {
-  // Handle error
-}
-// Continue
-// STRICT - Try/catch
-try {
-  await validator.validateWebhook(...);
-  // Continue
-} catch (error) {
-  // Handle error
-}
-```
----
-## Factory Methods
-### WebhookValidationFactory
-The SDK provides factory methods for common scenarios:
-```typescript
-import {
-  WebhookValidationFactory,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-```
-### createProduction()
-Production-ready validator with strict validation and SHA512:
-```typescript
-const validator = WebhookValidationFactory.createProduction(logger);
-// Equivalent to:
-new WebhookValidationService({
-  strictValidation: true,
-  algorithm: SignatureAlgorithm.SHA512_WITH_RSA
-}, logger);
-```
-**Use for**: Production environments
-### createDevelopment()
-Development validator with lenient validation and SHA512:
-```typescript
-const validator = WebhookValidationFactory.createDevelopment(logger);
-// Equivalent to:
-new WebhookValidationService({
-  strictValidation: false,
-  algorithm: SignatureAlgorithm.SHA512_WITH_RSA
-}, logger);
-```
-**Use for**: Development and testing
-### createWithFallback()
-Validator that supports both SHA512 and MD5 with auto-detection:
-```typescript
-const validator = WebhookValidationFactory.createWithFallback(logger);
-// Equivalent to:
-new WebhookValidationService({
-  strictValidation: true,
-  algorithm: SignatureAlgorithm.SHA512_WITH_RSA  // Default, but auto-detects
-}, logger);
-```
-**Use for**: Environments with mixed webhook sources (modern and older systems)
----
-## Environment-Based Configuration
-### Pattern: Configuration from Environment
-```typescript
-import {
-  WebhookValidationService,
-  WebhookValidationFactory,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-function createValidator() {
-  const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-  const env = process.env.NODE_ENV || 'development';
-  switch (env) {
-    case 'production':
-      return WebhookValidationFactory.createProduction(logger);
-    case 'development':
-    case 'test':
-      return WebhookValidationFactory.createDevelopment(logger);
-    default:
-      return WebhookValidationFactory.createWithFallback(logger);
-  }
-}
-// Usage
-const validator = createValidator();
-```
-### Pattern: Configuration Object
-```typescript
-interface AppConfig {
-  webhook: {
-    strictValidation: boolean;
-    algorithm: string;
-  };
-}
-function createValidatorFromConfig(config: AppConfig) {
-  const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-  return new WebhookValidationService({
-    strictValidation: config.webhook.strictValidation,
-    algorithm: config.webhook.algorithm === 'MD5'
-      ? SignatureAlgorithm.MD5_WITH_RSA
-      : SignatureAlgorithm.SHA512_WITH_RSA
-  }, logger);
-}
-// Usage
-const appConfig: AppConfig = {
-  webhook: {
-    strictValidation: true,
-    algorithm: 'SHA512'
-  }
-};
-const validator = createValidatorFromConfig(appConfig);
-```
----
-## Default Algorithm Selection
-The `algorithm` configuration option sets the **default** algorithm when auto-detection doesn't find a signature header:
-```typescript
-const validator = new WebhookValidationService({
-  algorithm: SignatureAlgorithm.MD5_WITH_RSA  // Default to MD5
-}, logger);
-// If headers have 'fluent-signature', uses SHA512 (auto-detected)
-// If headers have 'flex.signature', uses MD5 (auto-detected)
-// If no signature header found, uses MD5 (configured default)
-```
-**Best Practice**: Always use `SHA512_WITH_RSA` as default (it's the SDK default):
-```typescript
-// ✅ RECOMMENDED
-const validator = new WebhookValidationService({
-  algorithm: SignatureAlgorithm.SHA512_WITH_RSA  // Modern standard
-}, logger);
-// ⚠️ USE ONLY FOR OLDER SYSTEMS
-const validator = new WebhookValidationService({
-  algorithm: SignatureAlgorithm.MD5_WITH_RSA  // Support for older systems
-}, logger);
-```
----
-## Custom Validator Patterns
-### Pattern: Singleton Validator
-```typescript
-// validator.ts
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-let validatorInstance: WebhookValidationService | null = null;
-export function getValidator(): WebhookValidationService {
-  if (!validatorInstance) {
-    const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-    validatorInstance = new WebhookValidationService({
-      strictValidation: true
-    }, logger);
-  }
-  return validatorInstance;
-}
-// Usage
-import { getValidator } from './validator';
-const validator = getValidator();
-const result = await validator.validateWebhook(...);
-```
-### Pattern: Validator per Environment
-```typescript
-// validators.ts
-import {
-  WebhookValidationService,
-  WebhookValidationFactory,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-const baseLogger = createConsoleLogger();
-export const validators = {
-  production: WebhookValidationFactory.createProduction(
-    toStructuredLogger(baseLogger, { service: 'webhook-prod' })
-  ),
-  sandbox: WebhookValidationFactory.createDevelopment(
-    toStructuredLogger(baseLogger, { service: 'webhook-sandbox' })
-  ),
-  development: WebhookValidationFactory.createDevelopment(
-    toStructuredLogger(baseLogger, { service: 'webhook-dev' })
-  )
-};
-// Usage
-import { validators } from './validators';
-const env = process.env.FLUENT_ENV || 'development';
-const validator = validators[env];
-```
-### Pattern: Validator with Custom Logger
-```typescript
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-function createValidatorWithCustomLogging(logLevel: 'debug' | 'info' | 'warn' | 'error') {
-  const logger = toStructuredLogger(createConsoleLogger(), {
-    service: 'webhook',
-    logLevel
-  });
-  return new WebhookValidationService({
-    strictValidation: true
-  }, logger);
-}
-// Usage
-const validator = createValidatorWithCustomLogging('debug');
-```
----
-## Configuration Best Practices
-### 1. Use Factory Methods
-```typescript
-// ✅ GOOD - Use factory for common cases
-const validator = WebhookValidationFactory.createProduction(logger);
-// ❌ AVOID - Manual configuration for standard cases
-const validator = new WebhookValidationService({
-  strictValidation: true,
-  algorithm: SignatureAlgorithm.SHA512_WITH_RSA
-}, logger);
-```
-### 2. Environment-Specific Configuration
-```typescript
-// ✅ GOOD - Different configs per environment
-const validator = env === 'production'
-  ? WebhookValidationFactory.createProduction(logger)
-  : WebhookValidationFactory.createDevelopment(logger);
-// ❌ AVOID - Same config everywhere
-const validator = new WebhookValidationService({}, logger);
-```
-### 3. Strict Validation in Production
-```typescript
-// ✅ GOOD - Strict in production
-const validator = WebhookValidationFactory.createProduction(logger);
-// ⚠️ CAUTION - Lenient in production (less secure)
-const validator = WebhookValidationFactory.createDevelopment(logger);
-```
-### 4. Consistent Logging
-```typescript
-// ✅ GOOD - Consistent structured logger
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'app' });
-const validator = new WebhookValidationService({ strictValidation: true }, logger);
-// ❌ AVOID - Using console directly
-const validator = new WebhookValidationService({}, console);  // Not recommended
-```
----
-## Configuration Examples
-### Minimal Production Setup
-```typescript
-import {
-  WebhookValidationFactory,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-const validator = WebhookValidationFactory.createProduction(logger);
-```
-### Development Setup with Debugging
-```typescript
-import {
-  WebhookValidationFactory,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-const logger = toStructuredLogger(createConsoleLogger(), {
-  service: 'webhook-dev',
-  logLevel: 'debug'
-});
-const validator = WebhookValidationFactory.createDevelopment(logger);
-```
-### Multi-Environment Setup
-```typescript
-import {
-  WebhookValidationService,
-  SignatureAlgorithm,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-const configs = {
-  production: { strictValidation: true, algorithm: SignatureAlgorithm.SHA512_WITH_RSA },
-  sandbox: { strictValidation: false, algorithm: SignatureAlgorithm.SHA512_WITH_RSA },
-  compatible: { strictValidation: false, algorithm: SignatureAlgorithm.MD5_WITH_RSA }
-};
-const env = process.env.FLUENT_ENV as keyof typeof configs;
-const config = configs[env] || configs.production;
-const logger = toStructuredLogger(createConsoleLogger(), { service: `webhook-${env}` });
-const validator = new WebhookValidationService(config, logger);
-```
----
-## Key Takeaways
-- **Use factory methods** for common scenarios (production, development, fallback)
-- **Strict validation in production** - fail fast on invalid signatures
-- **Lenient validation in development** - better debugging experience
-- **Configure per environment** - different settings for prod/sandbox/dev
-- **SHA512 as default** - modern standard, more secure
-- **Consistent logging** - use same logger throughout application
----
-## Next Steps
-Continue to [Module 6: Error Handling](./webhook-validation-06-error-handling.md) to learn comprehensive error handling patterns.
----
-## Further Reading
-- [Module 7: API Reference](../../auto-pagination/modules/auto-pagination-07-api-reference.md) - Complete API documentation
-- [Module 2: Quick Start](../../auto-pagination/modules/auto-pagination-02-quick-start.md) - Basic usage patterns
+# Module 5: Configuration
+**Level:** Intermediate
+**Estimated Time:** 20 minutes
+## Overview
+This module covers all configuration options for WebhookValidationService, including factory methods for common scenarios, strict vs lenient validation, and custom configurations.
+## Learning Objectives
+By the end of this module, you will:
+- Understand all configuration options
+- Use factory methods for common scenarios
+- Configure strict vs lenient validation
+- Set default algorithms
+- Create custom validator configurations
+---
+## Configuration Options
+### WebhookValidationConfig Interface
+```typescript
+interface WebhookValidationConfig {
+  /**
+   * Throw errors on validation failure instead of returning result
+   * Default: false
+   */
+  strictValidation?: boolean;
+  /**
+   * Default algorithm to use if not auto-detected
+   * Default: SignatureAlgorithm.SHA512_WITH_RSA
+   */
+  algorithm?: SignatureAlgorithm;
+}
+```
+### Basic Configuration
+```typescript
+import {
+  WebhookValidationService,
+  SignatureAlgorithm,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+// Minimal configuration (uses defaults)
+const validator1 = new WebhookValidationService({}, logger);
+// With strict validation
+const validator2 = new WebhookValidationService({
+  strictValidation: true
+}, logger);
+// With default algorithm
+const validator3 = new WebhookValidationService({
+  algorithm: SignatureAlgorithm.MD5_WITH_RSA
+}, logger);
+// Complete configuration
+const validator4 = new WebhookValidationService({
+  strictValidation: true,
+  algorithm: SignatureAlgorithm.SHA512_WITH_RSA
+}, logger);
+```
+---
+## Strict vs Lenient Validation
+### Lenient Validation (Default)
+**Returns validation result** - doesn't throw errors:
+```typescript
+const validator = new WebhookValidationService({
+  strictValidation: false  // or omit (default)
+}, logger);
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (!result.isValid) {
+  // Handle validation failure gracefully
+  console.error('Validation failed:', result.error);
+  return { statusCode: 401, body: 'Invalid signature' };
+}
+// Continue with valid webhook
+```
+**Use when**:
+- You want to handle validation failures gracefully
+- You need custom error handling logic
+- You want to log additional context before failing
+- You're building a public API with detailed error responses
+### Strict Validation
+**Throws errors** on validation failure:
+```typescript
+const validator = new WebhookValidationService({
+  strictValidation: true
+}, logger);
+try {
+  const result = await validator.validateWebhook(rawBody, headers, publicKey);
+  // If we reach here, validation succeeded
+  console.log('Valid webhook using:', result.algorithm);
+} catch (error) {
+  // Validation failed - error thrown
+  console.error('Validation error:', error.message);
+  return { statusCode: 401, body: 'Invalid signature' };
+}
+```
+**Use when**:
+- You want fail-fast behavior
+- Validation failures should be treated as exceptions
+- You're using try/catch for error handling
+- You want cleaner code flow (no if/else checks)
+### Comparison
+```typescript
+// LENIENT - Check result
+const result = await validator.validateWebhook(...);
+if (!result.isValid) {
+  // Handle error
+}
+// Continue
+// STRICT - Try/catch
+try {
+  await validator.validateWebhook(...);
+  // Continue
+} catch (error) {
+  // Handle error
+}
+```
+---
+## Factory Methods
+### WebhookValidationFactory
+The SDK provides factory methods for common scenarios:
+```typescript
+import {
+  WebhookValidationFactory,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+```
+### createProduction()
+Production-ready validator with strict validation and SHA512:
+```typescript
+const validator = WebhookValidationFactory.createProduction(logger);
+// Equivalent to:
+new WebhookValidationService({
+  strictValidation: true,
+  algorithm: SignatureAlgorithm.SHA512_WITH_RSA
+}, logger);
+```
+**Use for**: Production environments
+### createDevelopment()
+Development validator with lenient validation and SHA512:
+```typescript
+const validator = WebhookValidationFactory.createDevelopment(logger);
+// Equivalent to:
+new WebhookValidationService({
+  strictValidation: false,
+  algorithm: SignatureAlgorithm.SHA512_WITH_RSA
+}, logger);
+```
+**Use for**: Development and testing
+### createWithFallback()
+Validator that supports both SHA512 and MD5 with auto-detection:
+```typescript
+const validator = WebhookValidationFactory.createWithFallback(logger);
+// Equivalent to:
+new WebhookValidationService({
+  strictValidation: true,
+  algorithm: SignatureAlgorithm.SHA512_WITH_RSA  // Default, but auto-detects
+}, logger);
+```
+**Use for**: Environments with mixed webhook sources (modern and older systems)
+---
+## Environment-Based Configuration
+### Pattern: Configuration from Environment
+```typescript
+import {
+  WebhookValidationService,
+  WebhookValidationFactory,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+function createValidator() {
+  const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+  const env = process.env.NODE_ENV || 'development';
+  switch (env) {
+    case 'production':
+      return WebhookValidationFactory.createProduction(logger);
+    case 'development':
+    case 'test':
+      return WebhookValidationFactory.createDevelopment(logger);
+    default:
+      return WebhookValidationFactory.createWithFallback(logger);
+  }
+}
+// Usage
+const validator = createValidator();
+```
+### Pattern: Configuration Object
+```typescript
+interface AppConfig {
+  webhook: {
+    strictValidation: boolean;
+    algorithm: string;
+  };
+}
+function createValidatorFromConfig(config: AppConfig) {
+  const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+  return new WebhookValidationService({
+    strictValidation: config.webhook.strictValidation,
+    algorithm: config.webhook.algorithm === 'MD5'
+      ? SignatureAlgorithm.MD5_WITH_RSA
+      : SignatureAlgorithm.SHA512_WITH_RSA
+  }, logger);
+}
+// Usage
+const appConfig: AppConfig = {
+  webhook: {
+    strictValidation: true,
+    algorithm: 'SHA512'
+  }
+};
+const validator = createValidatorFromConfig(appConfig);
+```
+---
+## Default Algorithm Selection
+The `algorithm` configuration option sets the **default** algorithm when auto-detection doesn't find a signature header:
+```typescript
+const validator = new WebhookValidationService({
+  algorithm: SignatureAlgorithm.MD5_WITH_RSA  // Default to MD5
+}, logger);
+// If headers have 'fluent-signature', uses SHA512 (auto-detected)
+// If headers have 'flex.signature', uses MD5 (auto-detected)
+// If no signature header found, uses MD5 (configured default)
+```
+**Best Practice**: Always use `SHA512_WITH_RSA` as default (it's the SDK default):
+```typescript
+// ✅ RECOMMENDED
+const validator = new WebhookValidationService({
+  algorithm: SignatureAlgorithm.SHA512_WITH_RSA  // Modern standard
+}, logger);
+// ⚠️ USE ONLY FOR OLDER SYSTEMS
+const validator = new WebhookValidationService({
+  algorithm: SignatureAlgorithm.MD5_WITH_RSA  // Support for older systems
+}, logger);
+```
+---
+## Custom Validator Patterns
+### Pattern: Singleton Validator
+```typescript
+// validator.ts
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+let validatorInstance: WebhookValidationService | null = null;
+export function getValidator(): WebhookValidationService {
+  if (!validatorInstance) {
+    const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+    validatorInstance = new WebhookValidationService({
+      strictValidation: true
+    }, logger);
+  }
+  return validatorInstance;
+}
+// Usage
+import { getValidator } from './validator';
+const validator = getValidator();
+const result = await validator.validateWebhook(...);
+```
+### Pattern: Validator per Environment
+```typescript
+// validators.ts
+import {
+  WebhookValidationService,
+  WebhookValidationFactory,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+const baseLogger = createConsoleLogger();
+export const validators = {
+  production: WebhookValidationFactory.createProduction(
+    toStructuredLogger(baseLogger, { service: 'webhook-prod' })
+  ),
+  sandbox: WebhookValidationFactory.createDevelopment(
+    toStructuredLogger(baseLogger, { service: 'webhook-sandbox' })
+  ),
+  development: WebhookValidationFactory.createDevelopment(
+    toStructuredLogger(baseLogger, { service: 'webhook-dev' })
+  )
+};
+// Usage
+import { validators } from './validators';
+const env = process.env.FLUENT_ENV || 'development';
+const validator = validators[env];
+```
+### Pattern: Validator with Custom Logger
+```typescript
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+function createValidatorWithCustomLogging(logLevel: 'debug' | 'info' | 'warn' | 'error') {
+  const logger = toStructuredLogger(createConsoleLogger(), {
+    service: 'webhook',
+    logLevel
+  });
+  return new WebhookValidationService({
+    strictValidation: true
+  }, logger);
+}
+// Usage
+const validator = createValidatorWithCustomLogging('debug');
+```
+---
+## Configuration Best Practices
+### 1. Use Factory Methods
+```typescript
+// ✅ GOOD - Use factory for common cases
+const validator = WebhookValidationFactory.createProduction(logger);
+// ❌ AVOID - Manual configuration for standard cases
+const validator = new WebhookValidationService({
+  strictValidation: true,
+  algorithm: SignatureAlgorithm.SHA512_WITH_RSA
+}, logger);
+```
+### 2. Environment-Specific Configuration
+```typescript
+// ✅ GOOD - Different configs per environment
+const validator = env === 'production'
+  ? WebhookValidationFactory.createProduction(logger)
+  : WebhookValidationFactory.createDevelopment(logger);
+// ❌ AVOID - Same config everywhere
+const validator = new WebhookValidationService({}, logger);
+```
+### 3. Strict Validation in Production
+```typescript
+// ✅ GOOD - Strict in production
+const validator = WebhookValidationFactory.createProduction(logger);
+// ⚠️ CAUTION - Lenient in production (less secure)
+const validator = WebhookValidationFactory.createDevelopment(logger);
+```
+### 4. Consistent Logging
+```typescript
+// ✅ GOOD - Consistent structured logger
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'app' });
+const validator = new WebhookValidationService({ strictValidation: true }, logger);
+// ❌ AVOID - Using console directly
+const validator = new WebhookValidationService({}, console);  // Not recommended
+```
+---
+## Configuration Examples
+### Minimal Production Setup
+```typescript
+import {
+  WebhookValidationFactory,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+const validator = WebhookValidationFactory.createProduction(logger);
+```
+### Development Setup with Debugging
+```typescript
+import {
+  WebhookValidationFactory,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+const logger = toStructuredLogger(createConsoleLogger(), {
+  service: 'webhook-dev',
+  logLevel: 'debug'
+});
+const validator = WebhookValidationFactory.createDevelopment(logger);
+```
+### Multi-Environment Setup
+```typescript
+import {
+  WebhookValidationService,
+  SignatureAlgorithm,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+const configs = {
+  production: { strictValidation: true, algorithm: SignatureAlgorithm.SHA512_WITH_RSA },
+  sandbox: { strictValidation: false, algorithm: SignatureAlgorithm.SHA512_WITH_RSA },
+  compatible: { strictValidation: false, algorithm: SignatureAlgorithm.MD5_WITH_RSA }
+};
+const env = process.env.FLUENT_ENV as keyof typeof configs;
+const config = configs[env] || configs.production;
+const logger = toStructuredLogger(createConsoleLogger(), { service: `webhook-${env}` });
+const validator = new WebhookValidationService(config, logger);
+```
+---
+## Key Takeaways
+- **Use factory methods** for common scenarios (production, development, fallback)
+- **Strict validation in production** - fail fast on invalid signatures
+- **Lenient validation in development** - better debugging experience
+- **Configure per environment** - different settings for prod/sandbox/dev
+- **SHA512 as default** - modern standard, more secure
+- **Consistent logging** - use same logger throughout application
+---
+## Next Steps
+Continue to [Module 6: Error Handling](./webhook-validation-06-error-handling.md) to learn comprehensive error handling patterns.
+---
+## Further Reading
+- [Module 7: API Reference](../../auto-pagination/modules/auto-pagination-07-api-reference.md) - Complete API documentation
+- [Module 2: Quick Start](../../auto-pagination/modules/auto-pagination-02-quick-start.md) - Basic usage patterns