@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-01-foundations.md

@@ -1,440 +1,440 @@
-# Module 1: Foundations
-
-**Level:** Beginner
-**Estimated Time:** 20 minutes
-
-## Overview
-
-This module covers the foundational concepts of webhook validation in the FC Connect SDK. You'll learn how cryptographic signatures protect webhooks, the algorithms Fluent Commerce uses, and the security model that ensures webhooks are authentic and untampered.
-
-## Learning Objectives
-
-By the end of this module, you will:
-- Understand how cryptographic webhook validation works
-- Know the difference between SHA512 and MD5 signature algorithms
-- Understand RSA public key cryptography basics
-- Know where to get and store public keys
-- Understand the security threats webhook validation prevents
-
----
-
-## What is Webhook Validation?
-
-**Webhook validation** is the process of cryptographically verifying that a webhook request:
-
-1. **Originates from Fluent Commerce** - Not a malicious actor
-2. **Has not been tampered with** - Payload integrity is intact
-3. **Is authentic** - Signature matches the expected public key
-
-### Webhook Validation Scope
-
-The SDK's `validateWebhook()` method is designed for **Fluent Commerce Rubix workflows** but technically works with **any system that implements RSA signature verification** with compatible algorithms (SHA512withRSA or MD5withRSA).
-
-**Key Requirement:** You must have access to the **public key** that matches the private key used to sign the webhook.
-
-**Common Use Cases:**
-- ✅ Fluent Commerce Rubix workflows (primary use case)
-- ✅ Any system using RSA signatures with SHA512 or MD5
-- ❌ Third-party webhooks using HMAC (Shopify, GitHub, Stripe) - requires manual validation
-
-### How It Works
-
-```
-┌─────────────────┐
-│ Fluent Commerce │
-│  Rubix Workflow │
-└────────┬────────┘
-         │
-         │ 1. Generate payload
-         │ 2. Sign with private key
-         │ 3. Add signature to header
-         ▼
-   ┌─────────────┐
-   │   Webhook   │
-   │   Request   │
-   └──────┬──────┘
-          │
-          │ Headers:
-          │   fluent-signature: <base64-signature>
-          │ Body:
-          │   { "eventId": "...", "data": {...} }
-          ▼
-   ┌──────────────────┐
-   │  Your Endpoint   │
-   │  (SDK Validator) │
-   └──────┬───────────┘
-          │
-          │ 1. Extract signature from header
-          │ 2. Verify using public key
-          │ 3. Confirm payload integrity
-          ▼
-   ┌──────────────┐
-   │ Valid ✓      │
-   │ Process Data │
-   └──────────────┘
-```
-
-### Why This Matters
-
-**Without validation**, your system could process:
-- Fake webhooks from attackers pretending to be Fluent Commerce
-- Modified payloads with altered order data, inventory counts, etc.
-- Replayed old webhooks to trigger duplicate processing
-- Malicious payloads designed to exploit your system
-
-**With validation**, you ensure:
-- Only genuine Fluent Commerce webhooks are processed
-- Data integrity is preserved end-to-end
-- Your system is protected from webhook-based attacks
-
----
-
-## Cryptographic Signatures Explained
-
-### RSA Signature Verification
-
-Fluent Commerce uses **RSA asymmetric cryptography** for webhook signatures:
-
-1. **Private Key** (Fluent Commerce has this)
-   - Used to **sign** webhook payloads
-   - Never shared, kept secure
-
-2. **Public Key** (You have this)
-   - Used to **verify** signatures
-   - Shared with integration partners
-   - Safe to distribute
-
-### The Signing Process
-
-```typescript
-// What Fluent Commerce does (you don't do this):
-const signature = crypto.sign(
-  'sha512',           // Hash algorithm
-  webhookPayload,     // Raw JSON body
-  privateKey          // Fluent's private key
-);
-
-// Add signature to header
-headers['fluent-signature'] = signature.toString('base64');
-```
-
-### The Verification Process
-
-```typescript
-// What the SDK does for you:
-const isValid = crypto.verify(
-  'sha512',           // Same hash algorithm
-  webhookPayload,     // Raw JSON body (must be identical)
-  publicKey,          // Your public key from Fluent
-  signature           // Signature from header
-);
-```
-
-**Key Point**: The signature is a cryptographic hash of the entire webhook body. If even one character changes, verification fails.
-
----
-
-## Supported Signature Algorithms
-
-Fluent Commerce supports two signature algorithms:
-
-### SHA512withRSA
-
-**Header:** `fluent-signature`
-**Algorithm:** `SHA512withRSA (RSASSA-PKCS1-v1_5)`
-**Status:** Used for Rubix workflows
-
-```typescript
-// Example header
-{
-  'fluent-signature': 'iQEcBAABCAAGBQJgm...',
-  'content-type': 'application/json'
-}
-```
-
-**Characteristics:**
-- 512-bit cryptographic hash
-- Used for Rubix workflows
-- Highly resistant to collision attacks
-
-### MD5withRSA
-
-**Header:** `flex.signature`
-**Algorithm:** `MD5withRSA (RSASSA-PKCS1-v1_5)`
-**Status:** Used for Flex workflows
-
-```typescript
-// Example header
-{
-  'flex.signature': 'oQEcBAABCAAGBQJgm...',
-  'content-type': 'application/json'
-}
-```
-
-**Characteristics:**
-- 128-bit hash algorithm
-- Used for Flex workflows
-- Less collision-resistant than SHA512
-
-### Algorithm Comparison
-
-| Feature | SHA512withRSA | MD5withRSA |
-|---------|---------------|------------|
-| **Header Name** | `fluent-signature` | `flex.signature` |
-| **Hash Strength** | 512-bit | 128-bit |
-| **Security** | High | Moderate |
-| **Collision Resistance** | Excellent | Adequate |
-| **Use Case** | Rubix workflows | Flex workflows |
-
-**Best Practice**: The SDK auto-detects which algorithm to use based on the header present.
-
----
-
-## Auto-Detection Pattern
-
-The SDK **automatically detects** which signature algorithm to use:
-
-```typescript
-// SDK checks headers in priority order:
-if (headers['fluent-signature']) {
-  // Use SHA512withRSA
-  algorithm = SignatureAlgorithm.SHA512_WITH_RSA;
-  signature = headers['fluent-signature'];
-} else if (headers['flex.signature']) {
-  // Use MD5withRSA
-  algorithm = SignatureAlgorithm.MD5_WITH_RSA;
-  signature = headers['flex.signature'];
-} else {
-  // No signature found - validation fails
-  return { isValid: false, error: 'No signature header found' };
-}
-```
-
-**You don't need to specify the algorithm** - the SDK handles it automatically.
-
----
-
-## Public Key Management
-
-### What is a Public Key?
-
-A **public key** is a cryptographic certificate that allows you to verify signatures created by Fluent Commerce's private key.
-
-**Format Options:**
-
-1. **Full PEM Format** (with headers):
-```
------BEGIN PUBLIC KEY-----
-MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAx...
------END PUBLIC KEY-----
-```
-
-2. **Raw Base64** (without headers):
-```
-MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAx...
-```
-
-**The SDK accepts both formats** and automatically adds PEM headers if missing.
-
-### Getting Your Public Key
-
-Contact your Fluent Commerce account team to obtain the public key for your environment:
-
-- **Production**: Production environment public key
-- **Sandbox**: Sandbox environment public key
-- **UAT**: UAT environment public key
-
-**Important**: Public keys are **environment-specific**. A production webhook cannot be validated with a sandbox public key.
-
-### Storing Public Keys Securely
-
-**Environment Variables** (Recommended):
-
-```bash
-# .env file
-FLUENT_WEBHOOK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIj...\n-----END PUBLIC KEY-----"
-```
-
-**Versori Variables**:
-
-```typescript
-// Access in Versori context
-const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
-```
-
-**Configuration Files** (Less secure):
-
-```json
-{
-  "fluent": {
-    "webhookPublicKey": "-----BEGIN PUBLIC KEY-----..."
-  }
-}
-```
-
-**Best Practices:**
-- Store in environment variables, not hardcoded in source
-- Use secrets management in production (AWS Secrets Manager, Azure Key Vault, etc.)
-- Never commit public keys to version control
-- Rotate keys periodically per security policy
-
----
-
-## Security Threats Prevented
-
-Webhook validation protects against several attack vectors:
-
-### 1. Impersonation Attacks
-
-**Threat**: Attacker sends fake webhook pretending to be Fluent Commerce
-
-```typescript
-// Malicious request
-POST /webhook
-{
-  "eventId": "fake-event",
-  "data": { "orderId": "123", "status": "CANCELLED" }
-}
-// No signature or invalid signature
-```
-
-**Protection**: Validation fails because signature is missing or invalid
-```typescript
-const result = await validator.validateWebhook(body, headers, publicKey);
-// result.isValid = false
-// result.error = "No signature header found"
-```
-
-### 2. Tampering Attacks
-
-**Threat**: Attacker intercepts webhook and modifies payload
-
-```typescript
-// Original webhook
-{ "orderId": "123", "amount": 100.00 }
-
-// Modified by attacker
-{ "orderId": "123", "amount": 0.01 }  // Changed amount
-```
-
-**Protection**: Signature verification fails because payload changed
-```typescript
-// Signature was created for original payload
-// Verification fails on modified payload
-const result = await validator.validateWebhook(modifiedBody, headers, publicKey);
-// result.isValid = false
-// result.error = "Signature verification failed"
-```
-
-### 3. Replay Attacks
-
-**Threat**: Attacker captures valid webhook and replays it multiple times
-
-```typescript
-// Attacker resends same webhook multiple times
-// to trigger duplicate order processing
-```
-
-**Protection**: Combine validation with timestamp checks and idempotency keys
-```typescript
-const result = await validator.validateWebhook(body, headers, publicKey);
-if (!result.isValid) throw new Error('Invalid signature');
-
-// Additional checks (your implementation)
-const data = JSON.parse(body);
-const eventTime = new Date(data.timestamp);
-const isRecent = Date.now() - eventTime.getTime() < 5 * 60 * 1000; // 5 min
-const isProcessed = await checkIfEventProcessed(data.eventId);
-
-if (!isRecent || isProcessed) {
-  throw new Error('Stale or duplicate webhook');
-}
-```
-
-### 4. Man-in-the-Middle Attacks
-
-**Threat**: Attacker intercepts and modifies webhook in transit
-
-**Protection**:
-- HTTPS encrypts webhook in transit
-- Signature validation detects any modifications
-- Combined protection ensures end-to-end security
-
----
-
-## The Validation Workflow
-
-Complete validation workflow in the SDK:
-
-```
-┌──────────────────────────────────────────────────────┐
-│ 1. Receive Webhook Request                          │
-│    - Extract raw body (must be unmodified string)   │
-│    - Extract headers object                         │
-└────────────────┬─────────────────────────────────────┘
-                 │
-                 ▼
-┌──────────────────────────────────────────────────────┐
-│ 2. Detect Signature Algorithm                       │
-│    - Check for 'fluent-signature' → SHA512          │
-│    - Check for 'flex.signature' → MD5               │
-│    - No signature found → Fail validation           │
-└────────────────┬─────────────────────────────────────┘
-                 │
-                 ▼
-┌──────────────────────────────────────────────────────┐
-│ 3. Extract Signature from Header                    │
-│    - Decode base64 signature                        │
-│    - Prepare for verification                       │
-└────────────────┬─────────────────────────────────────┘
-                 │
-                 ▼
-┌──────────────────────────────────────────────────────┐
-│ 4. Prepare Public Key                               │
-│    - Add PEM headers if missing                     │
-│    - Create verification object                     │
-└────────────────┬─────────────────────────────────────┘
-                 │
-                 ▼
-┌──────────────────────────────────────────────────────┐
-│ 5. Verify Signature                                 │
-│    - crypto.createVerify(algorithm)                 │
-│    - verify.update(rawBody)                         │
-│    - verify.verify(publicKey, signature, 'base64')  │
-└────────────────┬─────────────────────────────────────┘
-                 │
-                 ▼
-┌──────────────────────────────────────────────────────┐
-│ 6. Return Validation Result                         │
-│    - isValid: boolean                               │
-│    - algorithm: string                              │
-│    - error?: string                                 │
-│    - timestamp: Date                                │
-└──────────────────────────────────────────────────────┘
-```
-
----
-
-## Key Takeaways
-
-- **Webhook validation ensures authenticity and integrity** of webhooks from Fluent Commerce
-- **Two algorithms supported**: SHA512withRSA and MD5withRSA
-- **SDK auto-detects** which algorithm to use based on headers
-- **Public keys are environment-specific** - get the right key for prod/sandbox/UAT
-- **Validation prevents**: impersonation, tampering, replay, and MITM attacks
-- **Always use HTTPS** in production for encrypted transport
-- **Store public keys securely** in environment variables or secrets management
-
----
-
-## Next Steps
-
-Continue to [Module 2: Quick Start](../../auto-pagination/modules/auto-pagination-02-quick-start.md) to learn how to implement webhook validation in your code.
-
----
-
-## Further Reading
-
-- [Module 5: Configuration](./webhook-validation-05-configuration.md) - Advanced configuration options
-- [Module 6: Error Handling](./webhook-validation-06-error-handling.md) - Handling validation failures
-- [Module 7: API Reference](../../auto-pagination/modules/auto-pagination-07-api-reference.md) - Complete type definitions
+# Module 1: Foundations
+
+**Level:** Beginner
+**Estimated Time:** 20 minutes
+
+## Overview
+
+This module covers the foundational concepts of webhook validation in the FC Connect SDK. You'll learn how cryptographic signatures protect webhooks, the algorithms Fluent Commerce uses, and the security model that ensures webhooks are authentic and untampered.
+
+## Learning Objectives
+
+By the end of this module, you will:
+- Understand how cryptographic webhook validation works
+- Know the difference between SHA512 and MD5 signature algorithms
+- Understand RSA public key cryptography basics
+- Know where to get and store public keys
+- Understand the security threats webhook validation prevents
+
+---
+
+## What is Webhook Validation?
+
+**Webhook validation** is the process of cryptographically verifying that a webhook request:
+
+1. **Originates from Fluent Commerce** - Not a malicious actor
+2. **Has not been tampered with** - Payload integrity is intact
+3. **Is authentic** - Signature matches the expected public key
+
+### Webhook Validation Scope
+
+The SDK's `validateWebhook()` method is designed for **Fluent Commerce Rubix workflows** but technically works with **any system that implements RSA signature verification** with compatible algorithms (SHA512withRSA or MD5withRSA).
+
+**Key Requirement:** You must have access to the **public key** that matches the private key used to sign the webhook.
+
+**Common Use Cases:**
+- ✅ Fluent Commerce Rubix workflows (primary use case)
+- ✅ Any system using RSA signatures with SHA512 or MD5
+- ❌ Third-party webhooks using HMAC (Shopify, GitHub, Stripe) - requires manual validation
+
+### How It Works
+
+```
+┌─────────────────┐
+│ Fluent Commerce │
+│  Rubix Workflow │
+└────────┬────────┘
+         │
+         │ 1. Generate payload
+         │ 2. Sign with private key
+         │ 3. Add signature to header
+         ▼
+   ┌─────────────┐
+   │   Webhook   │
+   │   Request   │
+   └──────┬──────┘
+          │
+          │ Headers:
+          │   fluent-signature: <base64-signature>
+          │ Body:
+          │   { "eventId": "...", "data": {...} }
+          ▼
+   ┌──────────────────┐
+   │  Your Endpoint   │
+   │  (SDK Validator) │
+   └──────┬───────────┘
+          │
+          │ 1. Extract signature from header
+          │ 2. Verify using public key
+          │ 3. Confirm payload integrity
+          ▼
+   ┌──────────────┐
+   │ Valid ✓      │
+   │ Process Data │
+   └──────────────┘
+```
+
+### Why This Matters
+
+**Without validation**, your system could process:
+- Fake webhooks from attackers pretending to be Fluent Commerce
+- Modified payloads with altered order data, inventory counts, etc.
+- Replayed old webhooks to trigger duplicate processing
+- Malicious payloads designed to exploit your system
+
+**With validation**, you ensure:
+- Only genuine Fluent Commerce webhooks are processed
+- Data integrity is preserved end-to-end
+- Your system is protected from webhook-based attacks
+
+---
+
+## Cryptographic Signatures Explained
+
+### RSA Signature Verification
+
+Fluent Commerce uses **RSA asymmetric cryptography** for webhook signatures:
+
+1. **Private Key** (Fluent Commerce has this)
+   - Used to **sign** webhook payloads
+   - Never shared, kept secure
+
+2. **Public Key** (You have this)
+   - Used to **verify** signatures
+   - Shared with integration partners
+   - Safe to distribute
+
+### The Signing Process
+
+```typescript
+// What Fluent Commerce does (you don't do this):
+const signature = crypto.sign(
+  'sha512',           // Hash algorithm
+  webhookPayload,     // Raw JSON body
+  privateKey          // Fluent's private key
+);
+
+// Add signature to header
+headers['fluent-signature'] = signature.toString('base64');
+```
+
+### The Verification Process
+
+```typescript
+// What the SDK does for you:
+const isValid = crypto.verify(
+  'sha512',           // Same hash algorithm
+  webhookPayload,     // Raw JSON body (must be identical)
+  publicKey,          // Your public key from Fluent
+  signature           // Signature from header
+);
+```
+
+**Key Point**: The signature is a cryptographic hash of the entire webhook body. If even one character changes, verification fails.
+
+---
+
+## Supported Signature Algorithms
+
+Fluent Commerce supports two signature algorithms:
+
+### SHA512withRSA
+
+**Header:** `fluent-signature`
+**Algorithm:** `SHA512withRSA (RSASSA-PKCS1-v1_5)`
+**Status:** Used for Rubix workflows
+
+```typescript
+// Example header
+{
+  'fluent-signature': 'iQEcBAABCAAGBQJgm...',
+  'content-type': 'application/json'
+}
+```
+
+**Characteristics:**
+- 512-bit cryptographic hash
+- Used for Rubix workflows
+- Highly resistant to collision attacks
+
+### MD5withRSA
+
+**Header:** `flex.signature`
+**Algorithm:** `MD5withRSA (RSASSA-PKCS1-v1_5)`
+**Status:** Used for Flex workflows
+
+```typescript
+// Example header
+{
+  'flex.signature': 'oQEcBAABCAAGBQJgm...',
+  'content-type': 'application/json'
+}
+```
+
+**Characteristics:**
+- 128-bit hash algorithm
+- Used for Flex workflows
+- Less collision-resistant than SHA512
+
+### Algorithm Comparison
+
+| Feature | SHA512withRSA | MD5withRSA |
+|---------|---------------|------------|
+| **Header Name** | `fluent-signature` | `flex.signature` |
+| **Hash Strength** | 512-bit | 128-bit |
+| **Security** | High | Moderate |
+| **Collision Resistance** | Excellent | Adequate |
+| **Use Case** | Rubix workflows | Flex workflows |
+
+**Best Practice**: The SDK auto-detects which algorithm to use based on the header present.
+
+---
+
+## Auto-Detection Pattern
+
+The SDK **automatically detects** which signature algorithm to use:
+
+```typescript
+// SDK checks headers in priority order:
+if (headers['fluent-signature']) {
+  // Use SHA512withRSA
+  algorithm = SignatureAlgorithm.SHA512_WITH_RSA;
+  signature = headers['fluent-signature'];
+} else if (headers['flex.signature']) {
+  // Use MD5withRSA
+  algorithm = SignatureAlgorithm.MD5_WITH_RSA;
+  signature = headers['flex.signature'];
+} else {
+  // No signature found - validation fails
+  return { isValid: false, error: 'No signature header found' };
+}
+```
+
+**You don't need to specify the algorithm** - the SDK handles it automatically.
+
+---
+
+## Public Key Management
+
+### What is a Public Key?
+
+A **public key** is a cryptographic certificate that allows you to verify signatures created by Fluent Commerce's private key.
+
+**Format Options:**
+
+1. **Full PEM Format** (with headers):
+```
+-----BEGIN PUBLIC KEY-----
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAx...
+-----END PUBLIC KEY-----
+```
+
+2. **Raw Base64** (without headers):
+```
+MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAx...
+```
+
+**The SDK accepts both formats** and automatically adds PEM headers if missing.
+
+### Getting Your Public Key
+
+Contact your Fluent Commerce account team to obtain the public key for your environment:
+
+- **Production**: Production environment public key
+- **Sandbox**: Sandbox environment public key
+- **UAT**: UAT environment public key
+
+**Important**: Public keys are **environment-specific**. A production webhook cannot be validated with a sandbox public key.
+
+### Storing Public Keys Securely
+
+**Environment Variables** (Recommended):
+
+```bash
+# .env file
+FLUENT_WEBHOOK_PUBLIC_KEY="-----BEGIN PUBLIC KEY-----\nMIIBIj...\n-----END PUBLIC KEY-----"
+```
+
+**Versori Variables**:
+
+```typescript
+// Access in Versori context
+const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
+```
+
+**Configuration Files** (Less secure):
+
+```json
+{
+  "fluent": {
+    "webhookPublicKey": "-----BEGIN PUBLIC KEY-----..."
+  }
+}
+```
+
+**Best Practices:**
+- Store in environment variables, not hardcoded in source
+- Use secrets management in production (AWS Secrets Manager, Azure Key Vault, etc.)
+- Never commit public keys to version control
+- Rotate keys periodically per security policy
+
+---
+
+## Security Threats Prevented
+
+Webhook validation protects against several attack vectors:
+
+### 1. Impersonation Attacks
+
+**Threat**: Attacker sends fake webhook pretending to be Fluent Commerce
+
+```typescript
+// Malicious request
+POST /webhook
+{
+  "eventId": "fake-event",
+  "data": { "orderId": "123", "status": "CANCELLED" }
+}
+// No signature or invalid signature
+```
+
+**Protection**: Validation fails because signature is missing or invalid
+```typescript
+const result = await validator.validateWebhook(body, headers, publicKey);
+// result.isValid = false
+// result.error = "No signature header found"
+```
+
+### 2. Tampering Attacks
+
+**Threat**: Attacker intercepts webhook and modifies payload
+
+```typescript
+// Original webhook
+{ "orderId": "123", "amount": 100.00 }
+
+// Modified by attacker
+{ "orderId": "123", "amount": 0.01 }  // Changed amount
+```
+
+**Protection**: Signature verification fails because payload changed
+```typescript
+// Signature was created for original payload
+// Verification fails on modified payload
+const result = await validator.validateWebhook(modifiedBody, headers, publicKey);
+// result.isValid = false
+// result.error = "Signature verification failed"
+```
+
+### 3. Replay Attacks
+
+**Threat**: Attacker captures valid webhook and replays it multiple times
+
+```typescript
+// Attacker resends same webhook multiple times
+// to trigger duplicate order processing
+```
+
+**Protection**: Combine validation with timestamp checks and idempotency keys
+```typescript
+const result = await validator.validateWebhook(body, headers, publicKey);
+if (!result.isValid) throw new Error('Invalid signature');
+
+// Additional checks (your implementation)
+const data = JSON.parse(body);
+const eventTime = new Date(data.timestamp);
+const isRecent = Date.now() - eventTime.getTime() < 5 * 60 * 1000; // 5 min
+const isProcessed = await checkIfEventProcessed(data.eventId);
+
+if (!isRecent || isProcessed) {
+  throw new Error('Stale or duplicate webhook');
+}
+```
+
+### 4. Man-in-the-Middle Attacks
+
+**Threat**: Attacker intercepts and modifies webhook in transit
+
+**Protection**:
+- HTTPS encrypts webhook in transit
+- Signature validation detects any modifications
+- Combined protection ensures end-to-end security
+
+---
+
+## The Validation Workflow
+
+Complete validation workflow in the SDK:
+
+```
+┌──────────────────────────────────────────────────────┐
+│ 1. Receive Webhook Request                          │
+│    - Extract raw body (must be unmodified string)   │
+│    - Extract headers object                         │
+└────────────────┬─────────────────────────────────────┘
+                 │
+                 ▼
+┌──────────────────────────────────────────────────────┐
+│ 2. Detect Signature Algorithm                       │
+│    - Check for 'fluent-signature' → SHA512          │
+│    - Check for 'flex.signature' → MD5               │
+│    - No signature found → Fail validation           │
+└────────────────┬─────────────────────────────────────┘
+                 │
+                 ▼
+┌──────────────────────────────────────────────────────┐
+│ 3. Extract Signature from Header                    │
+│    - Decode base64 signature                        │
+│    - Prepare for verification                       │
+└────────────────┬─────────────────────────────────────┘
+                 │
+                 ▼
+┌──────────────────────────────────────────────────────┐
+│ 4. Prepare Public Key                               │
+│    - Add PEM headers if missing                     │
+│    - Create verification object                     │
+└────────────────┬─────────────────────────────────────┘
+                 │
+                 ▼
+┌──────────────────────────────────────────────────────┐
+│ 5. Verify Signature                                 │
+│    - crypto.createVerify(algorithm)                 │
+│    - verify.update(rawBody)                         │
+│    - verify.verify(publicKey, signature, 'base64')  │
+└────────────────┬─────────────────────────────────────┘
+                 │
+                 ▼
+┌──────────────────────────────────────────────────────┐
+│ 6. Return Validation Result                         │
+│    - isValid: boolean                               │
+│    - algorithm: string                              │
+│    - error?: string                                 │
+│    - timestamp: Date                                │
+└──────────────────────────────────────────────────────┘
+```
+
+---
+
+## Key Takeaways
+
+- **Webhook validation ensures authenticity and integrity** of webhooks from Fluent Commerce
+- **Two algorithms supported**: SHA512withRSA and MD5withRSA
+- **SDK auto-detects** which algorithm to use based on headers
+- **Public keys are environment-specific** - get the right key for prod/sandbox/UAT
+- **Validation prevents**: impersonation, tampering, replay, and MITM attacks
+- **Always use HTTPS** in production for encrypted transport
+- **Store public keys securely** in environment variables or secrets management
+
+---
+
+## Next Steps
+
+Continue to [Module 2: Quick Start](../../auto-pagination/modules/auto-pagination-02-quick-start.md) to learn how to implement webhook validation in your code.
+
+---
+
+## Further Reading
+
+- [Module 5: Configuration](./webhook-validation-05-configuration.md) - Advanced configuration options
+- [Module 6: Error Handling](./webhook-validation-06-error-handling.md) - Handling validation failures
+- [Module 7: API Reference](../../auto-pagination/modules/auto-pagination-07-api-reference.md) - Complete type definitions