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-07-api-reference.md CHANGED Viewed

@@ -1,511 +1,511 @@
-# Module 7: API Reference
-**Level:** Reference
-**Estimated Time:** As needed
-## Overview
-Complete API reference for the WebhookValidationService, including TypeScript type definitions, method signatures, and comprehensive documentation.
----
-## Core Classes
-### FluentClient.validateWebhook()
-Validates webhook authenticity using cryptographic signature verification.
-**Method Signature:**
-```typescript
-async validateWebhook(
-  payload: FluentWebhookPayload,
-  signature?: string,
-  rawPayload?: string
-): Promise<boolean>
-```
-**Parameters:**
-- `payload`: Parsed webhook payload object
-- `signature`: (Optional) Signature header value (e.g., from `x-signature`)
-- `rawPayload`: (Optional) Raw request body string (required for signature validation)
-**Returns:** `Promise<boolean>` - `true` if valid, `false` if invalid
-**Configuration Required:**
-FluentClient must be configured with `publicKey`:
-```typescript
-const client = await createClient({
-  baseUrl: 'https://api.fluentcommerce.com',
-  clientId: process.env.FLUENT_CLIENT_ID,
-  clientSecret: process.env.FLUENT_CLIENT_SECRET,
-  publicKey: process.env.FLUENT_WEBHOOK_PUBLIC_KEY  // Required for validation
-});
-```
-> **Note:** `validateWebhook()` is the **ONLY** FluentClient method that does NOT require `retailerId` configuration. This is because webhook validation is performed using RSA public key cryptography and does not require API authentication.
-**Examples:**
-1. **Basic Validation (Payload Structure Only):**
-```typescript
-const isValid = await client.validateWebhook(payload);
-// Validates: retailerId, accountId, entityType, rootEntityRef
-```
-2. **Signature Validation:**
-```typescript
-const signature = req.headers['x-signature'];
-const rawBody = req.body; // Raw string before JSON parsing
-const isValid = await client.validateWebhook(payload, signature, rawBody);
-// Validates: signature + payload structure
-```
-3. **Versori Platform:**
-```typescript
-export const handleWebhook = webhook('json', {
-  handler: async (activation) => {
-    const { payload, headers, body } = activation;
-    const client = await createClient(activation); // Auto-detects Versori context
-    const signature = headers['x-signature'];
-    const isValid = await client.validateWebhook(payload, signature, body);
-    if (!isValid) {
-      return { status: 401, message: 'Invalid webhook' };
-    }
-    // Process webhook...
-  }
-});
-```
-**Validation Logic:**
-1. If `signature` provided → Verify cryptographic signature using `publicKey`
-2. Validate payload structure (retailerId, accountId, entityType, rootEntityRef)
-3. Return `true` only if all validations pass
-**When to Use:**
-- Use `FluentClient.validateWebhook()` when you have a FluentClient instance
-- Use `WebhookValidationService` directly for standalone validation
-- Both use the same underlying validation
----
-### WebhookValidationService
-Main service for validating webhook signatures with RSA algorithms.
-```typescript
-class WebhookValidationService {
-  constructor(
-    config: WebhookValidationConfig,
-    logger: Logger
-  );
-  validateWebhook(
-    rawBody: string,
-    headers: Record<string, string>,
-    publicKey: string
-  ): Promise<WebhookValidationResult>;
-  validateWebhookSignature(
-    rawBody: string,
-    signature: string,
-    publicKey: string,
-    algorithm: SignatureAlgorithm
-  ): Promise<WebhookValidationResult>;
-}
-```
-#### Methods
-**validateWebhook()**
-- **Purpose**: Validate webhook with automatic algorithm detection
-- **Parameters**:
-  - `rawBody: string` - Raw request body (unmodified)
-  - `headers: Record<string, string>` - HTTP headers
-  - `publicKey: string` - Public key (PEM or base64)
-- **Returns**: `Promise<WebhookValidationResult>`
-- **Throws**: Error if strictValidation enabled and validation fails
-**validateWebhookSignature()**
-- **Purpose**: Validate with explicit algorithm selection
-- **Parameters**:
-  - `rawBody: string` - Raw request body
-  - `signature: string` - Base64-encoded signature
-  - `publicKey: string` - Public key (PEM or base64)
-  - `algorithm: SignatureAlgorithm` - Specific algorithm to use
-- **Returns**: `Promise<WebhookValidationResult>`
-- **Throws**: Error if strictValidation enabled and validation fails
----
-## Factory Class
-### WebhookValidationFactory
-Factory methods for common validator configurations.
-```typescript
-class WebhookValidationFactory {
-  static createProduction(logger: Logger): WebhookValidationService;
-  static createDevelopment(logger: Logger): WebhookValidationService;
-  static createWithFallback(logger: Logger): WebhookValidationService;
-}
-```
-#### Methods
-**createProduction()**
-- Creates validator with `strictValidation: true`, `algorithm: SHA512_WITH_RSA`
-- Use for production environments
-**createDevelopment()**
-- Creates validator with `strictValidation: false`, `algorithm: SHA512_WITH_RSA`
-- Use for development/testing
-**createWithFallback()**
-- Creates validator with `strictValidation: true`, supports both SHA512 and MD5
-- Use for environments with mixed webhook sources
----
-## Type Definitions
-### WebhookValidationConfig
-```typescript
-interface WebhookValidationConfig {
-  /**
-   * Throw errors on validation failure (default: false)
-   */
-  strictValidation?: boolean;
-  /**
-   * Default algorithm if not auto-detected (default: SHA512_WITH_RSA)
-   */
-  algorithm?: SignatureAlgorithm;
-}
-```
-### WebhookValidationResult
-```typescript
-interface WebhookValidationResult {
-  /**
-   * Whether signature validation succeeded
-   */
-  isValid: boolean;
-  /**
-   * Algorithm used for validation
-   */
-  algorithm: SignatureAlgorithm;
-  /**
-   * Error message if validation failed
-   */
-  error?: string;
-  /**
-   * Timestamp when validation occurred
-   */
-  timestamp: Date;
-}
-```
-### SignatureAlgorithm
-```typescript
-enum SignatureAlgorithm {
-  SHA512_WITH_RSA = 'SHA512withRSA',
-  MD5_WITH_RSA = 'MD5withRSA'
-}
-```
----
-## Best Practices
-### 1. Always Use Raw Body
-```typescript
-// ✅ CORRECT
-const rawBody = await request.text();
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-// ❌ WRONG
-const data = await request.json();
-const rawBody = JSON.stringify(data);  // May change whitespace/order
-```
-### 2. Check isValid Before Processing
-```typescript
-// ✅ CORRECT
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (!result.isValid) {
-  return { statusCode: 401 };
-}
-const data = JSON.parse(rawBody);
-// ❌ WRONG
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-const data = JSON.parse(rawBody);  // Parse before checking isValid
-if (!result.isValid) { /* too late */ }
-```
-### 3. Use Environment Variables for Public Keys
-```typescript
-// ✅ CORRECT
-const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-// ❌ WRONG
-const publicKey = "-----BEGIN PUBLIC KEY-----...";  // Hardcoded
-```
-### 4. Return Appropriate HTTP Status Codes
-```typescript
-// ✅ CORRECT
-if (!publicKey) return { statusCode: 500 };  // Server error
-if (!signature) return { statusCode: 400 };  // Bad request
-if (!result.isValid) return { statusCode: 401 };  // Unauthorized
-// ❌ WRONG
-if (!result.isValid) return { statusCode: 500 };  // Wrong code
-```
-### 5. Log Security Events
-```typescript
-// ✅ CORRECT
-if (!result.isValid) {
-  logger.warn('Invalid webhook signature', {
-    error: result.error,
-    sourceIp: req.ip
-  });
-}
-// ❌ WRONG
-if (!result.isValid) {
-  console.log('Invalid');  // No context, poor logging
-}
-```
----
-## FAQ
-### Q: Which algorithm should I use?
-**A**: Use `SHA512_WITH_RSA` (the SDK default). It's used by Fluent Commerce Rubix workflows. Use `MD5_WITH_RSA` for Flex workflows that require it.
-### Q: Do I need to specify the algorithm?
-**A**: No. The SDK auto-detects based on which signature header is present (`fluent-signature` for SHA512, `flex.signature` for MD5).
-### Q: Can I use parsed JSON body for validation?
-**A**: No. You must use the raw, unmodified request body. Parsing and re-stringifying may change whitespace or key order, breaking validation.
-### Q: What if validation always fails?
-**A**: Check:
-1. Using correct public key for environment (prod vs sandbox)
-2. Using raw body, not parsed and re-stringified
-3. Signature header is present in headers object
-4. Public key format is valid (PEM or base64)
-### Q: Should I use strict or lenient validation?
-**A**: Use strict (`strictValidation: true`) in production for fail-fast behavior. Use lenient (`false`) in development for better debugging.
-### Q: How do I handle multiple environments?
-**A**: Store separate public keys for each environment and select based on context:
-```typescript
-const publicKey = env === 'production'
-  ? process.env.FLUENT_WEBHOOK_PUBLIC_KEY_PROD
-  : process.env.FLUENT_WEBHOOK_PUBLIC_KEY_SANDBOX;
-```
-### Q: Can I validate webhooks from other sources?
-**A**: No. This service is specifically for Fluent Commerce Rubix workflows. Don't use it for webhooks from other systems.
-### Q: What's the difference between validateWebhook and validateWebhookSignature?
-**A**:
-- `validateWebhook()`: Auto-detects algorithm from headers (recommended)
-- `validateWebhookSignature()`: Explicit algorithm selection (advanced use cases)
-### Q: How do I test validation locally?
-**A**: Get a real webhook sample from Fluent Commerce test environment with valid signature. Don't try to generate signatures manually.
----
-## Security Considerations
-### Public Key Security
-- **Store in environment variables** or secrets management (AWS Secrets Manager, Azure Key Vault)
-- **Never commit to version control**
-- **Rotate periodically** per security policy
-- **Use environment-specific keys** (prod/sandbox/UAT)
-### Validation Security
-- **Always validate before processing** webhook data
-- **Return 401 for invalid signatures** (not detailed error messages)
-- **Log validation failures** for security monitoring
-- **Use HTTPS endpoints** in production
-- **Never log raw signatures** (security risk)
-### Implementation Security
-```typescript
-// ✅ CORRECT - Secure implementation
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (!result.isValid) {
-  logger.warn('Invalid signature');  // Log without details
-  return { statusCode: 401, body: 'Unauthorized' };  // Generic message
-}
-// ❌ WRONG - Leaks information
-if (!result.isValid) {
-  return {
-    statusCode: 401,
-    body: {
-      error: result.error,              // Exposes error details
-      publicKey: publicKey,              // Exposes key
-      signature: headers['fluent-signature']  // Exposes signature
-    }
-  };
-}
-```
----
-## Performance Considerations
-### Caching Validators
-```typescript
-// ✅ GOOD - Reuse validator instance
-const validator = WebhookValidationFactory.createProduction(logger);
-app.post('/webhook', async (req, res) => {
-  const result = await validator.validateWebhook(...);
-  // ...
-});
-// ❌ AVOID - Creating new validator per request
-app.post('/webhook', async (req, res) => {
-  const validator = new WebhookValidationService({}, logger);
-  const result = await validator.validateWebhook(...);
-});
-```
-### Async Validation
-Validation is already async - no additional optimization needed:
-```typescript
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-```
----
-## Migration Guide
-### From Manual Crypto Validation
-**Before**:
-```typescript
-const crypto = require('crypto');
-const verify = crypto.createVerify('sha512');
-verify.update(rawBody);
-const isValid = verify.verify(publicKey, signature, 'base64');
-```
-**After**:
-```typescript
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-const isValid = result.isValid;
-```
----
-## Complete TypeScript Example
-```typescript
-import {
-  WebhookValidationService,
-  WebhookValidationFactory,
-  SignatureAlgorithm,
-  WebhookValidationResult,
-  WebhookValidationConfig,
-  createConsoleLogger,
-  toStructuredLogger
-} from '@fluentcommerce/fc-connect-sdk';
-// Initialize services
-const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
-// Create validator (choose one)
-const validator1 = WebhookValidationFactory.createProduction(logger);
-const validator2 = new WebhookValidationService({
-  strictValidation: true,
-  algorithm: SignatureAlgorithm.SHA512_WITH_RSA
-}, logger);
-// Validate webhook
-async function handleWebhook(
-  rawBody: string,
-  headers: Record<string, string>,
-  publicKey: string
-): Promise<void> {
-  const result: WebhookValidationResult = await validator1.validateWebhook(
-    rawBody,
-    headers,
-    publicKey
-  );
-  if (!result.isValid) {
-    throw new Error(`Validation failed: ${result.error}`);
-  }
-  console.log('Valid webhook using:', result.algorithm);
-  const data = JSON.parse(rawBody);
-  // Process webhook
-}
-```
----
-## Key Takeaways
-- **Use factory methods** for common scenarios
-- **Auto-detection is preferred** - let SDK choose algorithm
-- **Raw body is mandatory** - never parse before validation
-- **Log security events** - track validation failures
-- **Return 401 for invalid signatures** - proper HTTP semantics
-- **Cache validator instances** - don't create per request
----
-## Related Documentation
-- [Module 1: Foundations](../../auto-pagination/modules/auto-pagination-01-foundations.md) - Core concepts
-- [Module 2: Quick Start](../../auto-pagination/modules/auto-pagination-02-quick-start.md) - Basic usage
-- [Module 5: Configuration](./webhook-validation-05-configuration.md) - Configuration options
-- [Module 6: Error Handling](./webhook-validation-06-error-handling.md) - Error handling patterns
-- [Quick Reference](../../advanced-services/advanced-services-quick-reference.md) - One-page cheat sheet
+# Module 7: API Reference
+**Level:** Reference
+**Estimated Time:** As needed
+## Overview
+Complete API reference for the WebhookValidationService, including TypeScript type definitions, method signatures, and comprehensive documentation.
+---
+## Core Classes
+### FluentClient.validateWebhook()
+Validates webhook authenticity using cryptographic signature verification.
+**Method Signature:**
+```typescript
+async validateWebhook(
+  payload: FluentWebhookPayload,
+  signature?: string,
+  rawPayload?: string
+): Promise<boolean>
+```
+**Parameters:**
+- `payload`: Parsed webhook payload object
+- `signature`: (Optional) Signature header value (e.g., from `x-signature`)
+- `rawPayload`: (Optional) Raw request body string (required for signature validation)
+**Returns:** `Promise<boolean>` - `true` if valid, `false` if invalid
+**Configuration Required:**
+FluentClient must be configured with `publicKey`:
+```typescript
+const client = await createClient({
+  baseUrl: 'https://api.fluentcommerce.com',
+  clientId: process.env.FLUENT_CLIENT_ID,
+  clientSecret: process.env.FLUENT_CLIENT_SECRET,
+  publicKey: process.env.FLUENT_WEBHOOK_PUBLIC_KEY  // Required for validation
+});
+```
+> **Note:** `validateWebhook()` is the **ONLY** FluentClient method that does NOT require `retailerId` configuration. This is because webhook validation is performed using RSA public key cryptography and does not require API authentication.
+**Examples:**
+1. **Basic Validation (Payload Structure Only):**
+```typescript
+const isValid = await client.validateWebhook(payload);
+// Validates: retailerId, accountId, entityType, rootEntityRef
+```
+2. **Signature Validation:**
+```typescript
+const signature = req.headers['x-signature'];
+const rawBody = req.body; // Raw string before JSON parsing
+const isValid = await client.validateWebhook(payload, signature, rawBody);
+// Validates: signature + payload structure
+```
+3. **Versori Platform:**
+```typescript
+export const handleWebhook = webhook('json', {
+  handler: async (activation) => {
+    const { payload, headers, body } = activation;
+    const client = await createClient(activation); // Auto-detects Versori context
+    const signature = headers['x-signature'];
+    const isValid = await client.validateWebhook(payload, signature, body);
+    if (!isValid) {
+      return { status: 401, message: 'Invalid webhook' };
+    }
+    // Process webhook...
+  }
+});
+```
+**Validation Logic:**
+1. If `signature` provided → Verify cryptographic signature using `publicKey`
+2. Validate payload structure (retailerId, accountId, entityType, rootEntityRef)
+3. Return `true` only if all validations pass
+**When to Use:**
+- Use `FluentClient.validateWebhook()` when you have a FluentClient instance
+- Use `WebhookValidationService` directly for standalone validation
+- Both use the same underlying validation
+---
+### WebhookValidationService
+Main service for validating webhook signatures with RSA algorithms.
+```typescript
+class WebhookValidationService {
+  constructor(
+    config: WebhookValidationConfig,
+    logger: Logger
+  );
+  validateWebhook(
+    rawBody: string,
+    headers: Record<string, string>,
+    publicKey: string
+  ): Promise<WebhookValidationResult>;
+  validateWebhookSignature(
+    rawBody: string,
+    signature: string,
+    publicKey: string,
+    algorithm: SignatureAlgorithm
+  ): Promise<WebhookValidationResult>;
+}
+```
+#### Methods
+**validateWebhook()**
+- **Purpose**: Validate webhook with automatic algorithm detection
+- **Parameters**:
+  - `rawBody: string` - Raw request body (unmodified)
+  - `headers: Record<string, string>` - HTTP headers
+  - `publicKey: string` - Public key (PEM or base64)
+- **Returns**: `Promise<WebhookValidationResult>`
+- **Throws**: Error if strictValidation enabled and validation fails
+**validateWebhookSignature()**
+- **Purpose**: Validate with explicit algorithm selection
+- **Parameters**:
+  - `rawBody: string` - Raw request body
+  - `signature: string` - Base64-encoded signature
+  - `publicKey: string` - Public key (PEM or base64)
+  - `algorithm: SignatureAlgorithm` - Specific algorithm to use
+- **Returns**: `Promise<WebhookValidationResult>`
+- **Throws**: Error if strictValidation enabled and validation fails
+---
+## Factory Class
+### WebhookValidationFactory
+Factory methods for common validator configurations.
+```typescript
+class WebhookValidationFactory {
+  static createProduction(logger: Logger): WebhookValidationService;
+  static createDevelopment(logger: Logger): WebhookValidationService;
+  static createWithFallback(logger: Logger): WebhookValidationService;
+}
+```
+#### Methods
+**createProduction()**
+- Creates validator with `strictValidation: true`, `algorithm: SHA512_WITH_RSA`
+- Use for production environments
+**createDevelopment()**
+- Creates validator with `strictValidation: false`, `algorithm: SHA512_WITH_RSA`
+- Use for development/testing
+**createWithFallback()**
+- Creates validator with `strictValidation: true`, supports both SHA512 and MD5
+- Use for environments with mixed webhook sources
+---
+## Type Definitions
+### WebhookValidationConfig
+```typescript
+interface WebhookValidationConfig {
+  /**
+   * Throw errors on validation failure (default: false)
+   */
+  strictValidation?: boolean;
+  /**
+   * Default algorithm if not auto-detected (default: SHA512_WITH_RSA)
+   */
+  algorithm?: SignatureAlgorithm;
+}
+```
+### WebhookValidationResult
+```typescript
+interface WebhookValidationResult {
+  /**
+   * Whether signature validation succeeded
+   */
+  isValid: boolean;
+  /**
+   * Algorithm used for validation
+   */
+  algorithm: SignatureAlgorithm;
+  /**
+   * Error message if validation failed
+   */
+  error?: string;
+  /**
+   * Timestamp when validation occurred
+   */
+  timestamp: Date;
+}
+```
+### SignatureAlgorithm
+```typescript
+enum SignatureAlgorithm {
+  SHA512_WITH_RSA = 'SHA512withRSA',
+  MD5_WITH_RSA = 'MD5withRSA'
+}
+```
+---
+## Best Practices
+### 1. Always Use Raw Body
+```typescript
+// ✅ CORRECT
+const rawBody = await request.text();
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+// ❌ WRONG
+const data = await request.json();
+const rawBody = JSON.stringify(data);  // May change whitespace/order
+```
+### 2. Check isValid Before Processing
+```typescript
+// ✅ CORRECT
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (!result.isValid) {
+  return { statusCode: 401 };
+}
+const data = JSON.parse(rawBody);
+// ❌ WRONG
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+const data = JSON.parse(rawBody);  // Parse before checking isValid
+if (!result.isValid) { /* too late */ }
+```
+### 3. Use Environment Variables for Public Keys
+```typescript
+// ✅ CORRECT
+const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+// ❌ WRONG
+const publicKey = "-----BEGIN PUBLIC KEY-----...";  // Hardcoded
+```
+### 4. Return Appropriate HTTP Status Codes
+```typescript
+// ✅ CORRECT
+if (!publicKey) return { statusCode: 500 };  // Server error
+if (!signature) return { statusCode: 400 };  // Bad request
+if (!result.isValid) return { statusCode: 401 };  // Unauthorized
+// ❌ WRONG
+if (!result.isValid) return { statusCode: 500 };  // Wrong code
+```
+### 5. Log Security Events
+```typescript
+// ✅ CORRECT
+if (!result.isValid) {
+  logger.warn('Invalid webhook signature', {
+    error: result.error,
+    sourceIp: req.ip
+  });
+}
+// ❌ WRONG
+if (!result.isValid) {
+  console.log('Invalid');  // No context, poor logging
+}
+```
+---
+## FAQ
+### Q: Which algorithm should I use?
+**A**: Use `SHA512_WITH_RSA` (the SDK default). It's used by Fluent Commerce Rubix workflows. Use `MD5_WITH_RSA` for Flex workflows that require it.
+### Q: Do I need to specify the algorithm?
+**A**: No. The SDK auto-detects based on which signature header is present (`fluent-signature` for SHA512, `flex.signature` for MD5).
+### Q: Can I use parsed JSON body for validation?
+**A**: No. You must use the raw, unmodified request body. Parsing and re-stringifying may change whitespace or key order, breaking validation.
+### Q: What if validation always fails?
+**A**: Check:
+1. Using correct public key for environment (prod vs sandbox)
+2. Using raw body, not parsed and re-stringified
+3. Signature header is present in headers object
+4. Public key format is valid (PEM or base64)
+### Q: Should I use strict or lenient validation?
+**A**: Use strict (`strictValidation: true`) in production for fail-fast behavior. Use lenient (`false`) in development for better debugging.
+### Q: How do I handle multiple environments?
+**A**: Store separate public keys for each environment and select based on context:
+```typescript
+const publicKey = env === 'production'
+  ? process.env.FLUENT_WEBHOOK_PUBLIC_KEY_PROD
+  : process.env.FLUENT_WEBHOOK_PUBLIC_KEY_SANDBOX;
+```
+### Q: Can I validate webhooks from other sources?
+**A**: No. This service is specifically for Fluent Commerce Rubix workflows. Don't use it for webhooks from other systems.
+### Q: What's the difference between validateWebhook and validateWebhookSignature?
+**A**:
+- `validateWebhook()`: Auto-detects algorithm from headers (recommended)
+- `validateWebhookSignature()`: Explicit algorithm selection (advanced use cases)
+### Q: How do I test validation locally?
+**A**: Get a real webhook sample from Fluent Commerce test environment with valid signature. Don't try to generate signatures manually.
+---
+## Security Considerations
+### Public Key Security
+- **Store in environment variables** or secrets management (AWS Secrets Manager, Azure Key Vault)
+- **Never commit to version control**
+- **Rotate periodically** per security policy
+- **Use environment-specific keys** (prod/sandbox/UAT)
+### Validation Security
+- **Always validate before processing** webhook data
+- **Return 401 for invalid signatures** (not detailed error messages)
+- **Log validation failures** for security monitoring
+- **Use HTTPS endpoints** in production
+- **Never log raw signatures** (security risk)
+### Implementation Security
+```typescript
+// ✅ CORRECT - Secure implementation
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (!result.isValid) {
+  logger.warn('Invalid signature');  // Log without details
+  return { statusCode: 401, body: 'Unauthorized' };  // Generic message
+}
+// ❌ WRONG - Leaks information
+if (!result.isValid) {
+  return {
+    statusCode: 401,
+    body: {
+      error: result.error,              // Exposes error details
+      publicKey: publicKey,              // Exposes key
+      signature: headers['fluent-signature']  // Exposes signature
+    }
+  };
+}
+```
+---
+## Performance Considerations
+### Caching Validators
+```typescript
+// ✅ GOOD - Reuse validator instance
+const validator = WebhookValidationFactory.createProduction(logger);
+app.post('/webhook', async (req, res) => {
+  const result = await validator.validateWebhook(...);
+  // ...
+});
+// ❌ AVOID - Creating new validator per request
+app.post('/webhook', async (req, res) => {
+  const validator = new WebhookValidationService({}, logger);
+  const result = await validator.validateWebhook(...);
+});
+```
+### Async Validation
+Validation is already async - no additional optimization needed:
+```typescript
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+```
+---
+## Migration Guide
+### From Manual Crypto Validation
+**Before**:
+```typescript
+const crypto = require('crypto');
+const verify = crypto.createVerify('sha512');
+verify.update(rawBody);
+const isValid = verify.verify(publicKey, signature, 'base64');
+```
+**After**:
+```typescript
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+const isValid = result.isValid;
+```
+---
+## Complete TypeScript Example
+```typescript
+import {
+  WebhookValidationService,
+  WebhookValidationFactory,
+  SignatureAlgorithm,
+  WebhookValidationResult,
+  WebhookValidationConfig,
+  createConsoleLogger,
+  toStructuredLogger
+} from '@fluentcommerce/fc-connect-sdk';
+// Initialize services
+const logger = toStructuredLogger(createConsoleLogger(), { service: 'webhook' });
+// Create validator (choose one)
+const validator1 = WebhookValidationFactory.createProduction(logger);
+const validator2 = new WebhookValidationService({
+  strictValidation: true,
+  algorithm: SignatureAlgorithm.SHA512_WITH_RSA
+}, logger);
+// Validate webhook
+async function handleWebhook(
+  rawBody: string,
+  headers: Record<string, string>,
+  publicKey: string
+): Promise<void> {
+  const result: WebhookValidationResult = await validator1.validateWebhook(
+    rawBody,
+    headers,
+    publicKey
+  );
+  if (!result.isValid) {
+    throw new Error(`Validation failed: ${result.error}`);
+  }
+  console.log('Valid webhook using:', result.algorithm);
+  const data = JSON.parse(rawBody);
+  // Process webhook
+}
+```
+---
+## Key Takeaways
+- **Use factory methods** for common scenarios
+- **Auto-detection is preferred** - let SDK choose algorithm
+- **Raw body is mandatory** - never parse before validation
+- **Log security events** - track validation failures
+- **Return 401 for invalid signatures** - proper HTTP semantics
+- **Cache validator instances** - don't create per request
+---
+## Related Documentation
+- [Module 1: Foundations](../../auto-pagination/modules/auto-pagination-01-foundations.md) - Core concepts
+- [Module 2: Quick Start](../../auto-pagination/modules/auto-pagination-02-quick-start.md) - Basic usage
+- [Module 5: Configuration](./webhook-validation-05-configuration.md) - Configuration options
+- [Module 6: Error Handling](./webhook-validation-06-error-handling.md) - Error handling patterns
+- [Quick Reference](../../advanced-services/advanced-services-quick-reference.md) - One-page cheat sheet