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

@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

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 (476) hide show

package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-02-quick-start.md CHANGED Viewed

@@ -1,525 +1,525 @@
-# Module 2: Quick Start
-**Level:** Beginner
-**Estimated Time:** 15 minutes
-## Overview
-This module gets you started with webhook validation immediately. You'll learn the basic usage pattern, auto-detection features, and how to validate your first webhook in just a few lines of code.
-## Learning Objectives
-By the end of this module, you will:
-- Implement basic webhook validation
-- Understand the auto-detection pattern
-- Know how to handle validation results
-- Test webhook validation locally
-- Build a complete working example
----
-## Basic Validation Pattern
-### Minimal Example
-```typescript
-import {
-  WebhookValidationService,
-  createConsoleLogger
-} from '@fluentcommerce/fc-connect-sdk';
-// 1. Initialize logging
-const logger = createConsoleLogger();
-// 2. Create validator
-const validator = new WebhookValidationService({
-  strictValidation: true  // Throw errors on validation failure
-}, logger);
-// 3. Validate webhook (auto-detects signature type)
-const result = await validator.validateWebhook(
-  rawBody,        // Raw request body as string
-  headers,        // Request headers object
-  publicKey       // Public key from Fluent Commerce
-);
-// 4. Check result
-if (!result.isValid) {
-  console.error('Invalid webhook:', result.error);
-  return { statusCode: 401, body: 'Invalid signature' };
-}
-// 5. Process valid webhook
-console.log('Valid webhook using:', result.algorithm);
-const data = JSON.parse(rawBody);
-// ... your business logic here
-```
-**That's the complete pattern.** The SDK handles algorithm detection, signature extraction, and cryptographic verification automatically.
-> **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.
----
-## Understanding the Parameters
-### 1. Raw Body (Critical)
-**Must be the exact string** received in the webhook request:
-```typescript
-// ✅ CORRECT - Raw string body
-const rawBody = await request.text();
-const rawBody = req.body.toString();  // If using express.raw()
-// ❌ WRONG - Parsed or modified body
-const rawBody = JSON.stringify(req.body);  // Don't stringify parsed JSON
-const rawBody = req.body.data;             // Don't use parsed fields
-```
-**Why this matters**: The signature is created from the exact byte sequence of the original body. Any modification (even whitespace changes) breaks validation.
-### 2. Headers Object
-Standard HTTP headers object with signature header:
-```typescript
-// Example headers object
-const headers = {
-  'fluent-signature': 'iQEcBAABCAAGBQJgm...',
-  'content-type': 'application/json',
-  'user-agent': 'Fluent-Webhook/1.0'
-};
-// From Express.js
-const headers = req.headers;
-// From Versori (use ctx.request() to access Express request)
-const req = ctx.request();
-const headers = req?.headers || {};
-// From fetch API
-const headers = Object.fromEntries(request.headers.entries());
-```
-**Signature headers** the SDK looks for (in priority order):
-1. `fluent-signature` (SHA512withRSA)
-2. `flex.signature` (MD5withRSA)
-### 3. Public Key
-Public key from Fluent Commerce for your environment:
-```typescript
-// From environment variable (recommended)
-const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
-// From Versori variable
-const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
-// From configuration
-const publicKey = config.fluent.webhookPublicKey;
-// Hardcoded (development only - not recommended)
-const publicKey = "-----BEGIN PUBLIC KEY-----\nMIIBIj...\n-----END PUBLIC KEY-----";
-```
-**Formats accepted**:
-- Full PEM with headers: `-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----`
-- Raw base64: `MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...`
-The SDK automatically adds PEM headers if missing.
----
-## Auto-Detection in Action
-The SDK automatically detects which signature algorithm to use:
-```typescript
-// Webhook with SHA512 signature
-const headers1 = {
-  'fluent-signature': 'abc123...',
-  'content-type': 'application/json'
-};
-const result1 = await validator.validateWebhook(rawBody, headers1, publicKey);
-// result1.algorithm = 'SHA512withRSA'
-// Webhook with MD5 signature (for Flex workflows)
-const headers2 = {
-  'flex.signature': 'xyz789...',
-  'content-type': 'application/json'
-};
-const result2 = await validator.validateWebhook(rawBody, headers2, publicKey);
-// result2.algorithm = 'MD5withRSA'
-// Webhook with no signature
-const headers3 = {
-  'content-type': 'application/json'
-};
-const result3 = await validator.validateWebhook(rawBody, headers3, publicKey);
-// result3.isValid = false
-// result3.error = 'No signature header found'
-```
-**You don't need to specify the algorithm** - the SDK handles it automatically based on which header is present.
----
-## Handling Validation Results
-### Validation Result Structure
-```typescript
-interface WebhookValidationResult {
-  isValid: boolean;           // true if signature verified successfully
-  algorithm: SignatureAlgorithm;  // Which algorithm was used
-  error?: string;             // Error message if validation failed
-  timestamp: Date;            // When validation occurred
-}
-```
-### Success Case
-```typescript
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (result.isValid) {
-  console.log(`Valid webhook using ${result.algorithm}`);
-  console.log(`Validated at ${result.timestamp.toISOString()}`);
-  // Safe to process webhook data
-  const data = JSON.parse(rawBody);
-  await processWebhookData(data);
-  return { statusCode: 200, body: 'Success' };
-}
-```
-### Failure Case
-```typescript
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (!result.isValid) {
-  console.error(`Validation failed: ${result.error}`);
-  console.error(`Attempted algorithm: ${result.algorithm}`);
-  // Log for security monitoring
-  logger.warn('Invalid webhook signature', {
-    error: result.error,
-    timestamp: result.timestamp,
-    headers: headers
-  });
-  // Return 401 Unauthorized
-  return { statusCode: 401, body: 'Invalid signature' };
-}
-```
----
-## Complete Working Example
-### Standalone Validation Script
-```typescript
-import {
-  WebhookValidationService,
-  SignatureAlgorithm,
-  createConsoleLogger
-} from '@fluentcommerce/fc-connect-sdk';
-async function validateWebhook(
-  rawBody: string,
-  headers: Record<string, string>,
-  publicKey: string
-): Promise<boolean> {
-  // Initialize logging
-  const logger = createConsoleLogger();
-  // Create validator with strict validation
-  const validator = new WebhookValidationService({
-    strictValidation: true
-  }, logger);
-  try {
-    // Validate webhook (auto-detects algorithm)
-    const result = await validator.validateWebhook(
-      rawBody,
-      headers,
-      publicKey
-    );
-    if (!result.isValid) {
-      logger.error('Webhook validation failed', {
-        error: result.error,
-        algorithm: result.algorithm,
-        timestamp: result.timestamp
-      });
-      return false;
-    }
-    logger.info('Webhook validated successfully', {
-      algorithm: result.algorithm,
-      timestamp: result.timestamp
-    });
-    return true;
-  } catch (error) {
-    logger.error('Validation error', { error });
-    return false;
-  }
-}
-// Usage
-const isValid = await validateWebhook(
-  requestBody,
-  requestHeaders,
-  process.env.FLUENT_WEBHOOK_PUBLIC_KEY!
-);
-if (isValid) {
-  const webhookData = JSON.parse(requestBody);
-  console.log('Processing webhook:', webhookData.eventId);
-  // ... process webhook
-} else {
-  console.error('Rejecting invalid webhook');
-}
-```
----
-## Testing Validation
-### Test with Sample Data
-```typescript
-import {
-  WebhookValidationService,
-  createConsoleLogger
-} from '@fluentcommerce/fc-connect-sdk';
-async function testValidation() {
-  const logger = createConsoleLogger();
-  const validator = new WebhookValidationService({
-    strictValidation: false  // Lenient for testing
-  }, logger);
-  // Sample webhook payload
-  const webhookBody = JSON.stringify({
-    eventId: 'evt_123',
-    entityType: 'ORDER',
-    entityId: 'order_456',
-    timestamp: new Date().toISOString(),
-    data: {
-      ref: 'ORD-123',
-      status: 'PLACED'
-    }
-  });
-  // Sample headers (get real signature from Fluent Commerce)
-  const webhookHeaders = {
-    'fluent-signature': 'YOUR_TEST_SIGNATURE_HERE',
-    'content-type': 'application/json'
-  };
-  const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY!;
-  // Validate
-  const result = await validator.validateWebhook(
-    webhookBody,
-    webhookHeaders,
-    publicKey
-  );
-  console.log('Validation test result:', {
-    isValid: result.isValid,
-    algorithm: result.algorithm,
-    error: result.error,
-    timestamp: result.timestamp
-  });
-}
-testValidation();
-```
-### Local Testing Tips
-1. **Get a real webhook sample** from Fluent Commerce test environment
-2. **Capture the exact raw body** - don't modify or reformat
-3. **Extract the signature header** - `fluent-signature` or `flex.signature`
-4. **Use the correct public key** for the environment (sandbox/production)
-5. **Test with both algorithms** to ensure your code handles both
----
-## Common Patterns
-### Pattern 1: Validate Then Parse
-```typescript
-// ✅ CORRECT - Validate before parsing
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (!result.isValid) {
-  throw new Error('Invalid signature');
-}
-const data = JSON.parse(rawBody);  // Safe to parse now
-```
-### Pattern 2: Early Return on Failure
-```typescript
-// ✅ CORRECT - Fail fast pattern
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (!result.isValid) {
-  return { statusCode: 401, body: 'Unauthorized' };
-}
-// Continue processing valid webhook
-const data = JSON.parse(rawBody);
-await processWebhookData(data);
-return { statusCode: 200, body: 'Success' };
-```
-### Pattern 3: Logging for Security Monitoring
-```typescript
-// ✅ CORRECT - Log validation failures for security team
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (!result.isValid) {
-  logger.warn('Webhook validation failed', {
-    error: result.error,
-    timestamp: result.timestamp,
-    sourceIp: request.ip,           // Track source
-    algorithm: result.algorithm,
-    hasSignature: !!headers['fluent-signature'] || !!headers['flex.signature']
-  });
-  // Optionally alert security team if many failures
-  if (await tooManyFailures()) {
-    await alertSecurityTeam('Multiple webhook validation failures detected');
-  }
-  return { statusCode: 401, body: 'Unauthorized' };
-}
-```
----
-## Quick Troubleshooting
-### Problem: Validation Always Fails
-**Check 1**: Are you using the raw body?
-```typescript
-// ✅ CORRECT
-const rawBody = await request.text();
-// ❌ WRONG
-const rawBody = JSON.stringify(request.json());
-```
-**Check 2**: Is the public key correct?
-```typescript
-console.log('Public key starts with:', publicKey.substring(0, 30));
-// Should start with "-----BEGIN PUBLIC KEY-----" or "MIIBIj"
-```
-**Check 3**: Is the signature header present?
-```typescript
-console.log('Headers:', headers);
-console.log('Has fluent-signature:', !!headers['fluent-signature']);
-console.log('Has flex.signature:', !!headers['flex.signature']);
-```
-**Check 4**: Are you using the right environment's key?
-```typescript
-// Production webhook needs production public key
-// Sandbox webhook needs sandbox public key
-console.log('Environment:', process.env.NODE_ENV);
-console.log('Using key for:', process.env.FLUENT_ENV);
-```
----
-## Key Takeaways
-- **Basic pattern**: Create validator → call `validateWebhook()` → check `isValid`
-- **Auto-detection works**: SDK automatically selects SHA512 or MD5 based on headers
-- **Use raw body**: Never parse or modify body before validation
-- **Check isValid**: Always check result before processing webhook data
-- **Log failures**: Track validation failures for security monitoring
-- **Return 401**: Return unauthorized status for invalid signatures
----
-## Practice Exercise
-Create a simple webhook validator that:
-1. Accepts a webhook payload and headers
-2. Validates the signature using the SDK
-3. Logs the validation result
-4. Returns success/failure status
-<details>
-<summary>Solution</summary>
-```typescript
-import {
-  WebhookValidationService,
-  createConsoleLogger
-} from '@fluentcommerce/fc-connect-sdk';
-async function handleWebhook(
-  rawBody: string,
-  headers: Record<string, string>
-): Promise<{ statusCode: number; body: string }> {
-  // Setup
-  const logger = createConsoleLogger();
-  const validator = new WebhookValidationService({ strictValidation: true }, logger);
-  const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY!;
-  // Validate
-  const result = await validator.validateWebhook(rawBody, headers, publicKey);
-  // Log result
-  logger.info('Validation result', {
-    isValid: result.isValid,
-    algorithm: result.algorithm,
-    error: result.error
-  });
-  // Return response
-  if (!result.isValid) {
-    return { statusCode: 401, body: 'Invalid signature' };
-  }
-  const data = JSON.parse(rawBody);
-  logger.info('Processing webhook', { eventId: data.eventId });
-  return { statusCode: 200, body: 'Success' };
-}
-```
-</details>
----
-## Next Steps
-Continue to [Module 3: Versori Integration](./webhook-validation-03-versori-integration.md) to learn how to integrate webhook validation in Versori connectors.
----
-## Further Reading
-- [Module 4: Platform Integration](./webhook-validation-04-platform-integration.md) - Express.js and other platforms
-- [Module 5: Configuration](./webhook-validation-05-configuration.md) - Advanced configuration options
-- [Module 6: Error Handling](./webhook-validation-06-error-handling.md) - Comprehensive error handling patterns
+# Module 2: Quick Start
+**Level:** Beginner
+**Estimated Time:** 15 minutes
+## Overview
+This module gets you started with webhook validation immediately. You'll learn the basic usage pattern, auto-detection features, and how to validate your first webhook in just a few lines of code.
+## Learning Objectives
+By the end of this module, you will:
+- Implement basic webhook validation
+- Understand the auto-detection pattern
+- Know how to handle validation results
+- Test webhook validation locally
+- Build a complete working example
+---
+## Basic Validation Pattern
+### Minimal Example
+```typescript
+import {
+  WebhookValidationService,
+  createConsoleLogger
+} from '@fluentcommerce/fc-connect-sdk';
+// 1. Initialize logging
+const logger = createConsoleLogger();
+// 2. Create validator
+const validator = new WebhookValidationService({
+  strictValidation: true  // Throw errors on validation failure
+}, logger);
+// 3. Validate webhook (auto-detects signature type)
+const result = await validator.validateWebhook(
+  rawBody,        // Raw request body as string
+  headers,        // Request headers object
+  publicKey       // Public key from Fluent Commerce
+);
+// 4. Check result
+if (!result.isValid) {
+  console.error('Invalid webhook:', result.error);
+  return { statusCode: 401, body: 'Invalid signature' };
+}
+// 5. Process valid webhook
+console.log('Valid webhook using:', result.algorithm);
+const data = JSON.parse(rawBody);
+// ... your business logic here
+```
+**That's the complete pattern.** The SDK handles algorithm detection, signature extraction, and cryptographic verification automatically.
+> **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.
+---
+## Understanding the Parameters
+### 1. Raw Body (Critical)
+**Must be the exact string** received in the webhook request:
+```typescript
+// ✅ CORRECT - Raw string body
+const rawBody = await request.text();
+const rawBody = req.body.toString();  // If using express.raw()
+// ❌ WRONG - Parsed or modified body
+const rawBody = JSON.stringify(req.body);  // Don't stringify parsed JSON
+const rawBody = req.body.data;             // Don't use parsed fields
+```
+**Why this matters**: The signature is created from the exact byte sequence of the original body. Any modification (even whitespace changes) breaks validation.
+### 2. Headers Object
+Standard HTTP headers object with signature header:
+```typescript
+// Example headers object
+const headers = {
+  'fluent-signature': 'iQEcBAABCAAGBQJgm...',
+  'content-type': 'application/json',
+  'user-agent': 'Fluent-Webhook/1.0'
+};
+// From Express.js
+const headers = req.headers;
+// From Versori (use ctx.request() to access Express request)
+const req = ctx.request();
+const headers = req?.headers || {};
+// From fetch API
+const headers = Object.fromEntries(request.headers.entries());
+```
+**Signature headers** the SDK looks for (in priority order):
+1. `fluent-signature` (SHA512withRSA)
+2. `flex.signature` (MD5withRSA)
+### 3. Public Key
+Public key from Fluent Commerce for your environment:
+```typescript
+// From environment variable (recommended)
+const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY;
+// From Versori variable
+const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
+// From configuration
+const publicKey = config.fluent.webhookPublicKey;
+// Hardcoded (development only - not recommended)
+const publicKey = "-----BEGIN PUBLIC KEY-----\nMIIBIj...\n-----END PUBLIC KEY-----";
+```
+**Formats accepted**:
+- Full PEM with headers: `-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----`
+- Raw base64: `MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8A...`
+The SDK automatically adds PEM headers if missing.
+---
+## Auto-Detection in Action
+The SDK automatically detects which signature algorithm to use:
+```typescript
+// Webhook with SHA512 signature
+const headers1 = {
+  'fluent-signature': 'abc123...',
+  'content-type': 'application/json'
+};
+const result1 = await validator.validateWebhook(rawBody, headers1, publicKey);
+// result1.algorithm = 'SHA512withRSA'
+// Webhook with MD5 signature (for Flex workflows)
+const headers2 = {
+  'flex.signature': 'xyz789...',
+  'content-type': 'application/json'
+};
+const result2 = await validator.validateWebhook(rawBody, headers2, publicKey);
+// result2.algorithm = 'MD5withRSA'
+// Webhook with no signature
+const headers3 = {
+  'content-type': 'application/json'
+};
+const result3 = await validator.validateWebhook(rawBody, headers3, publicKey);
+// result3.isValid = false
+// result3.error = 'No signature header found'
+```
+**You don't need to specify the algorithm** - the SDK handles it automatically based on which header is present.
+---
+## Handling Validation Results
+### Validation Result Structure
+```typescript
+interface WebhookValidationResult {
+  isValid: boolean;           // true if signature verified successfully
+  algorithm: SignatureAlgorithm;  // Which algorithm was used
+  error?: string;             // Error message if validation failed
+  timestamp: Date;            // When validation occurred
+}
+```
+### Success Case
+```typescript
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (result.isValid) {
+  console.log(`Valid webhook using ${result.algorithm}`);
+  console.log(`Validated at ${result.timestamp.toISOString()}`);
+  // Safe to process webhook data
+  const data = JSON.parse(rawBody);
+  await processWebhookData(data);
+  return { statusCode: 200, body: 'Success' };
+}
+```
+### Failure Case
+```typescript
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (!result.isValid) {
+  console.error(`Validation failed: ${result.error}`);
+  console.error(`Attempted algorithm: ${result.algorithm}`);
+  // Log for security monitoring
+  logger.warn('Invalid webhook signature', {
+    error: result.error,
+    timestamp: result.timestamp,
+    headers: headers
+  });
+  // Return 401 Unauthorized
+  return { statusCode: 401, body: 'Invalid signature' };
+}
+```
+---
+## Complete Working Example
+### Standalone Validation Script
+```typescript
+import {
+  WebhookValidationService,
+  SignatureAlgorithm,
+  createConsoleLogger
+} from '@fluentcommerce/fc-connect-sdk';
+async function validateWebhook(
+  rawBody: string,
+  headers: Record<string, string>,
+  publicKey: string
+): Promise<boolean> {
+  // Initialize logging
+  const logger = createConsoleLogger();
+  // Create validator with strict validation
+  const validator = new WebhookValidationService({
+    strictValidation: true
+  }, logger);
+  try {
+    // Validate webhook (auto-detects algorithm)
+    const result = await validator.validateWebhook(
+      rawBody,
+      headers,
+      publicKey
+    );
+    if (!result.isValid) {
+      logger.error('Webhook validation failed', {
+        error: result.error,
+        algorithm: result.algorithm,
+        timestamp: result.timestamp
+      });
+      return false;
+    }
+    logger.info('Webhook validated successfully', {
+      algorithm: result.algorithm,
+      timestamp: result.timestamp
+    });
+    return true;
+  } catch (error) {
+    logger.error('Validation error', { error });
+    return false;
+  }
+}
+// Usage
+const isValid = await validateWebhook(
+  requestBody,
+  requestHeaders,
+  process.env.FLUENT_WEBHOOK_PUBLIC_KEY!
+);
+if (isValid) {
+  const webhookData = JSON.parse(requestBody);
+  console.log('Processing webhook:', webhookData.eventId);
+  // ... process webhook
+} else {
+  console.error('Rejecting invalid webhook');
+}
+```
+---
+## Testing Validation
+### Test with Sample Data
+```typescript
+import {
+  WebhookValidationService,
+  createConsoleLogger
+} from '@fluentcommerce/fc-connect-sdk';
+async function testValidation() {
+  const logger = createConsoleLogger();
+  const validator = new WebhookValidationService({
+    strictValidation: false  // Lenient for testing
+  }, logger);
+  // Sample webhook payload
+  const webhookBody = JSON.stringify({
+    eventId: 'evt_123',
+    entityType: 'ORDER',
+    entityId: 'order_456',
+    timestamp: new Date().toISOString(),
+    data: {
+      ref: 'ORD-123',
+      status: 'PLACED'
+    }
+  });
+  // Sample headers (get real signature from Fluent Commerce)
+  const webhookHeaders = {
+    'fluent-signature': 'YOUR_TEST_SIGNATURE_HERE',
+    'content-type': 'application/json'
+  };
+  const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY!;
+  // Validate
+  const result = await validator.validateWebhook(
+    webhookBody,
+    webhookHeaders,
+    publicKey
+  );
+  console.log('Validation test result:', {
+    isValid: result.isValid,
+    algorithm: result.algorithm,
+    error: result.error,
+    timestamp: result.timestamp
+  });
+}
+testValidation();
+```
+### Local Testing Tips
+1. **Get a real webhook sample** from Fluent Commerce test environment
+2. **Capture the exact raw body** - don't modify or reformat
+3. **Extract the signature header** - `fluent-signature` or `flex.signature`
+4. **Use the correct public key** for the environment (sandbox/production)
+5. **Test with both algorithms** to ensure your code handles both
+---
+## Common Patterns
+### Pattern 1: Validate Then Parse
+```typescript
+// ✅ CORRECT - Validate before parsing
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (!result.isValid) {
+  throw new Error('Invalid signature');
+}
+const data = JSON.parse(rawBody);  // Safe to parse now
+```
+### Pattern 2: Early Return on Failure
+```typescript
+// ✅ CORRECT - Fail fast pattern
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (!result.isValid) {
+  return { statusCode: 401, body: 'Unauthorized' };
+}
+// Continue processing valid webhook
+const data = JSON.parse(rawBody);
+await processWebhookData(data);
+return { statusCode: 200, body: 'Success' };
+```
+### Pattern 3: Logging for Security Monitoring
+```typescript
+// ✅ CORRECT - Log validation failures for security team
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (!result.isValid) {
+  logger.warn('Webhook validation failed', {
+    error: result.error,
+    timestamp: result.timestamp,
+    sourceIp: request.ip,           // Track source
+    algorithm: result.algorithm,
+    hasSignature: !!headers['fluent-signature'] || !!headers['flex.signature']
+  });
+  // Optionally alert security team if many failures
+  if (await tooManyFailures()) {
+    await alertSecurityTeam('Multiple webhook validation failures detected');
+  }
+  return { statusCode: 401, body: 'Unauthorized' };
+}
+```
+---
+## Quick Troubleshooting
+### Problem: Validation Always Fails
+**Check 1**: Are you using the raw body?
+```typescript
+// ✅ CORRECT
+const rawBody = await request.text();
+// ❌ WRONG
+const rawBody = JSON.stringify(request.json());
+```
+**Check 2**: Is the public key correct?
+```typescript
+console.log('Public key starts with:', publicKey.substring(0, 30));
+// Should start with "-----BEGIN PUBLIC KEY-----" or "MIIBIj"
+```
+**Check 3**: Is the signature header present?
+```typescript
+console.log('Headers:', headers);
+console.log('Has fluent-signature:', !!headers['fluent-signature']);
+console.log('Has flex.signature:', !!headers['flex.signature']);
+```
+**Check 4**: Are you using the right environment's key?
+```typescript
+// Production webhook needs production public key
+// Sandbox webhook needs sandbox public key
+console.log('Environment:', process.env.NODE_ENV);
+console.log('Using key for:', process.env.FLUENT_ENV);
+```
+---
+## Key Takeaways
+- **Basic pattern**: Create validator → call `validateWebhook()` → check `isValid`
+- **Auto-detection works**: SDK automatically selects SHA512 or MD5 based on headers
+- **Use raw body**: Never parse or modify body before validation
+- **Check isValid**: Always check result before processing webhook data
+- **Log failures**: Track validation failures for security monitoring
+- **Return 401**: Return unauthorized status for invalid signatures
+---
+## Practice Exercise
+Create a simple webhook validator that:
+1. Accepts a webhook payload and headers
+2. Validates the signature using the SDK
+3. Logs the validation result
+4. Returns success/failure status
+<details>
+<summary>Solution</summary>
+```typescript
+import {
+  WebhookValidationService,
+  createConsoleLogger
+} from '@fluentcommerce/fc-connect-sdk';
+async function handleWebhook(
+  rawBody: string,
+  headers: Record<string, string>
+): Promise<{ statusCode: number; body: string }> {
+  // Setup
+  const logger = createConsoleLogger();
+  const validator = new WebhookValidationService({ strictValidation: true }, logger);
+  const publicKey = process.env.FLUENT_WEBHOOK_PUBLIC_KEY!;
+  // Validate
+  const result = await validator.validateWebhook(rawBody, headers, publicKey);
+  // Log result
+  logger.info('Validation result', {
+    isValid: result.isValid,
+    algorithm: result.algorithm,
+    error: result.error
+  });
+  // Return response
+  if (!result.isValid) {
+    return { statusCode: 401, body: 'Invalid signature' };
+  }
+  const data = JSON.parse(rawBody);
+  logger.info('Processing webhook', { eventId: data.eventId });
+  return { statusCode: 200, body: 'Success' };
+}
+```
+</details>
+---
+## Next Steps
+Continue to [Module 3: Versori Integration](./webhook-validation-03-versori-integration.md) to learn how to integrate webhook validation in Versori connectors.
+---
+## Further Reading
+- [Module 4: Platform Integration](./webhook-validation-04-platform-integration.md) - Express.js and other platforms
+- [Module 5: Configuration](./webhook-validation-05-configuration.md) - Advanced configuration options
+- [Module 6: Error Handling](./webhook-validation-06-error-handling.md) - Comprehensive error handling patterns