@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-03-versori-integration.md

@@ -1,741 +1,741 @@
-# Module 3: Versori Integration
-
-**Level:** Intermediate
-**Estimated Time:** 25 minutes
-
-## Overview
-
-This module covers **Fluent webhook signature validation** integration with the Versori platform.
-
-**IMPORTANT DISTINCTION**: This is about validating **Fluent Commerce webhook signatures** (cryptographic verification), which is DIFFERENT from **Versori webhook authentication** (platform-level connection-based auth). You'll learn how to validate Fluent webhooks in Versori webhook handlers, access public keys from Versori variables, handle raw body extraction, and implement production-ready Versori webhook connectors.
-
-## Learning Objectives
-
-By the end of this module, you will:
-
-- Understand the difference between Versori webhook auth and Fluent signature validation
-- Integrate Fluent signature validation in Versori webhook handlers
-- Access public keys from Versori variables
-- Handle raw body extraction across Versori versions
-- Implement complete Versori webhook connectors with validation
-- Handle Versori-specific edge cases
-
----
-
-## Versori Webhook Auth vs Fluent Signature Validation
-
-**CRITICAL DISTINCTION** - These are TWO DIFFERENT security mechanisms:
-
-### Versori Webhook Authentication (Platform-Level)
-
-**Purpose**: Verify webhook caller is authorized to trigger your Versori workflow
-**Mechanism**: Connection-based authentication parameter
-**Configuration**: `webhook('name', { connection: 'conn-name' })`
-**Validation**: Versori platform validates BEFORE your code runs
-**Use Case**: Restrict who can call your webhook endpoint
-
-```typescript
-// ✅ Versori webhook auth (platform validates caller)
-export const myWebhook = webhook('my-webhook', {
-  connection: 'my-connection'  // Platform-level auth
-}, async (ctx) => {
-  // Only runs if caller authenticated via connection
-});
-```
-
-### Fluent Signature Validation (Application-Level)
-
-**Purpose**: Verify webhook payload came from Fluent Commerce and wasn't tampered with
-**Mechanism**: Cryptographic signature verification (HMAC-SHA256/SHA512)
-**Configuration**: Use `WebhookValidationService` in your code
-**Validation**: YOUR code validates using Fluent's public key
-**Use Case**: Verify webhook content authenticity and integrity
-
-```typescript
-// ✅ Fluent signature validation (your code validates content)
-export const fluentWebhook = webhook('fluent-webhook', async (ctx) => {
-  const { log } = ctx;  // Versori native log
-  const logger = toStructuredLogger(log, { service: 'webhook-validation' });
-  const validator = new WebhookValidationService({ strictValidation: true }, logger);
-  const result = await validator.validateWebhook(rawBody, headers, publicKey);
-  // Only process if Fluent signature is valid
-});
-```
-
-### When to Use Which?
-
-| Scenario | Versori Auth | Fluent Validation |
-|----------|-------------|-------------------|
-| **Public webhook from Fluent** | ❌ Not needed | ✅ Required |
-| **Restricted webhook access** | ✅ Recommended | ✅ Also use |
-| **Verify payload integrity** | ❌ Doesn't check | ✅ Required |
-| **Multi-source webhooks** | ✅ Per-source | ✅ Per-source |
-
-**Best Practice**: Use BOTH for Fluent webhooks:
-1. **Versori auth** restricts WHO can call your endpoint
-2. **Fluent validation** verifies WHAT content is authentic
-
----
-
-## Versori Webhook Pattern
-
-### Complete Versori Webhook with Validation
-
-```typescript
-import { webhook } from '@versori/run';
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const fluentWebhook = webhook('fluent-webhook', async ctx => {
-  // 1. Wrap Versori native log for SDK services
-  const { log } = ctx;  // Versori native log
-  const structuredLogger = toStructuredLogger(log, {
-    service: 'webhook-validation',
-  });
-
-  // Why wrap? SDK services expect StructuredLogger interface with:
-  // - debug(), info(), warn(), error() methods
-  // - Context object with service/module/correlationId
-  // - Native Versori log provides basic methods but no context
-
-  // 2. Create validator (requires StructuredLogger)
-  const validator = new WebhookValidationService(
-    {
-      strictValidation: true,
-    },
-    structuredLogger  // Must be StructuredLogger, not native log
-  );
-
-  // 3. Get public key from Versori variables
-  const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
-  if (!publicKey) {
-    structuredLogger.error('Missing public key in Versori variables');
-    return { statusCode: 500, body: 'Server configuration error' };
-  }
-
-  // 4. Extract raw body (version-aware)
-  const rawBody =
-    ctx.request && typeof ctx.request.text === 'function'
-      ? await ctx.request.text() // Versori v0.2.29+
-      : JSON.stringify(ctx.data); // Older versions
-
-  // 5. Validate webhook
-  const req = ctx.request();
-  const headers = req?.headers || {};
-  const result = await validator.validateWebhook(rawBody, headers, publicKey);
-
-  // 6. Handle invalid signature
-  if (!result.isValid) {
-    structuredLogger.warn('Invalid webhook signature', {
-      error: result.error,
-      algorithm: result.algorithm,
-    });
-    return { statusCode: 401, body: 'Invalid signature' };
-  }
-
-  // 7. Process valid webhook
-  structuredLogger.info('Valid webhook received', { algorithm: result.algorithm });
-  const data = JSON.parse(rawBody);
-
-  // Your business logic here
-  await processFluentWebhook(data);
-
-  return { statusCode: 200, body: 'Success' };
-});
-```
-
----
-
-## Versori Context Object
-
-### Understanding ctx Object
-
-Versori provides a rich context object to webhook handlers:
-
-```typescript
-interface VersoriWebhookContext {
-  // Request data
-  data: any; // Parsed JSON body
-  headers: Record<string, string>; // Request headers
-  request?: Request; // Raw Request object (v0.2.29+)
-
-  // Versori variables
-  vars: Record<string, string>; // Environment variables
-
-  // Logging
-  log: (message: string, ...args: any[]) => void;
-
-  // Other Versori utilities
-  activation: {
-    id: string;
-    workflowId: string;
-    // ... more activation metadata
-  };
-}
-```
-
-### Accessing Components
-
-```typescript
-export const myWebhook = webhook('my-webhook', async ctx => {
-  // Parsed data (already JSON parsed by Versori)
-  const eventId = ctx.data.eventId;
-
-  // Headers
-  const req = ctx.request();
-  const signature = req?.headers['fluent-signature'] as string;
-
-  // Environment variables
-  const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
-  const env = ctx.vars.ENVIRONMENT;
-
-  // Logging
-  ctx.log('Processing webhook', eventId);
-
-  // Activation metadata
-  const workflowId = ctx.activation.workflowId;
-});
-```
-
----
-
-## Raw Body Extraction
-
-### Version-Aware Raw Body Extraction
-
-Versori changed how raw bodies are accessed in version 0.2.29:
-
-```typescript
-/**
- * Extract raw request body - handles both old and new Versori versions
- */
-async function getRawBody(ctx: any): Promise<string> {
-  // Versori v0.2.29+ provides Request object with text() method
-  if (ctx.request && typeof ctx.request.text === 'function') {
-    return await ctx.request.text();
-  }
-
-  // Older Versori versions - reconstruct from parsed data
-  if (ctx.data) {
-    return JSON.stringify(ctx.data);
-  }
-
-  throw new Error('Unable to extract raw body from context');
-}
-
-// Usage in webhook
-export const myWebhook = webhook('my-webhook', async ctx => {
-  const rawBody = await getRawBody(ctx); // Works across versions
-  // ... validate with rawBody
-});
-```
-
-### Why Raw Body Matters
-
-```typescript
-// ❌ WRONG - Using pre-parsed data
-const rawBody = JSON.stringify(ctx.data);
-// Problem: JSON.stringify may reorder keys, change whitespace
-// This breaks signature verification
-
-// ✅ CORRECT - Use original raw body
-const rawBody = await ctx.request.text();
-// This preserves exact byte sequence for signature verification
-```
-
-**Best Practice**: Always use `ctx.request.text()` when available (Versori v0.2.29+). For older versions, `JSON.stringify(ctx.data)` is acceptable but may have edge cases.
-
----
-
-## Versori Variables for Public Keys
-
-### Setting Up Versori Variables
-
-In Versori platform UI:
-
-1. Navigate to your workflow
-2. Go to **Variables** tab
-3. Add variable: `FLUENT_WEBHOOK_PUBLIC_KEY`
-4. Set value to your Fluent Commerce public key
-5. Mark as **Secret** for security
-
-```typescript
-// Access in webhook handler
-const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
-```
-
-### Multiple Environment Keys
-
-For workflows that handle multiple environments (prod/sandbox):
-
-```typescript
-// Set multiple variables in Versori
-// FLUENT_WEBHOOK_PUBLIC_KEY_PROD
-// FLUENT_WEBHOOK_PUBLIC_KEY_SANDBOX
-
-// Access based on environment
-export const myWebhook = webhook('my-webhook', async ctx => {
-  const env = ctx.vars.ENVIRONMENT || 'production';
-
-  const publicKey =
-    env === 'production'
-      ? ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY_PROD
-      : ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY_SANDBOX;
-
-  if (!publicKey) {
-    throw new Error(`Missing public key for environment: ${env}`);
-  }
-
-  // ... validate with environment-specific key
-});
-```
-
----
-
-## Complete Versori Connector Example
-
-### Production-Ready Webhook Connector
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import {
-  WebhookValidationService,
-  WebhookValidationResult,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Fluent Commerce webhook handler with validation
- */
-export const fluentOrderWebhook = webhook('fluent-order-webhook')
-  .then(
-    fn('validate', async ctx => {
-      // Initialize services
-      const { log } = ctx;  // Versori native log
-      const logger = toStructuredLogger(log, {
-        service: 'webhook-validator',
-      });
-
-      // Get configuration
-      const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
-      if (!publicKey) {
-        throw new Error('FLUENT_WEBHOOK_PUBLIC_KEY not configured in Versori variables');
-      }
-
-      // Extract raw body
-      const rawBody =
-        ctx.request && typeof ctx.request.text === 'function'
-          ? await ctx.request.text()
-          : JSON.stringify(ctx.data);
-
-      // Create validator
-      const validator = new WebhookValidationService(
-        {
-          strictValidation: true,
-        },
-        logger
-      );
-
-      // Validate signature
-      const req = ctx.request();
-      const headers = req?.headers || {};
-      const result: WebhookValidationResult = await validator.validateWebhook(
-        rawBody,
-        headers,
-        publicKey
-      );
-
-      // Handle validation failure
-      if (!result.isValid) {
-        logger.error('Webhook validation failed', {
-          error: result.error,
-          algorithm: result.algorithm,
-          workflowId: ctx.activation.workflowId,
-          headers: Object.keys(headers),
-        });
-
-        throw new Error(`Invalid webhook signature: ${result.error}`);
-      }
-
-      // Log successful validation
-      logger.info('Webhook validated successfully', {
-        algorithm: result.algorithm,
-        timestamp: result.timestamp,
-        workflowId: ctx.activation.workflowId,
-      });
-
-      // Parse and return data
-      const webhookData = JSON.parse(rawBody);
-      return {
-        ...ctx,
-        data: webhookData,
-        validationResult: result,
-      };
-    })
-  )
-  .then(
-    fn('processOrder', async ctx => {
-      // Access validated webhook data
-      const { eventId, entityType, entityId, data } = ctx.data;
-
-      ctx.log('Processing validated webhook', {
-        eventId,
-        entityType,
-        entityId,
-      });
-
-      // Your business logic here
-      if (entityType === 'ORDER') {
-        await processOrder(data);
-      }
-
-      return {
-        success: true,
-        eventId,
-        processedAt: new Date().toISOString(),
-      };
-    })
-  )
-  .catch(({ error, data }) => {
-    // Handle validation or processing errors
-    console.error('Webhook processing failed', { error });
-
-    return {
-      success: false,
-      error: error.message,
-      timestamp: new Date().toISOString(),
-    };
-  });
-
-// Helper function
-async function processOrder(orderData: any): Promise<void> {
-  // Your order processing logic
-  console.log('Processing order:', orderData.ref);
-}
-```
-
----
-
-## Versori Response Patterns
-
-### Standard JSON Response
-
-```typescript
-export const webhook1 = webhook('webhook1', async ctx => {
-  const req = ctx.request();
-  const headers = req?.headers || {};
-  const result = await validator.validateWebhook(rawBody, headers, publicKey);
-
-  if (!result.isValid) {
-    return {
-      statusCode: 401,
-      body: { error: 'Invalid signature', details: result.error },
-    };
-  }
-
-  return {
-    statusCode: 200,
-    body: { success: true, eventId: ctx.data.eventId },
-  };
-});
-```
-
-### Custom Response Headers
-
-```typescript
-export const webhook2 = webhook('webhook2', async ctx => {
-  const req = ctx.request();
-  const headers = req?.headers || {};
-  const result = await validator.validateWebhook(rawBody, headers, publicKey);
-
-  if (!result.isValid) {
-    return {
-      statusCode: 401,
-      headers: { 'X-Validation-Error': result.error },
-      body: 'Unauthorized',
-    };
-  }
-
-  return {
-    statusCode: 200,
-    headers: { 'X-Validation-Algorithm': result.algorithm },
-    body: 'Success',
-  };
-});
-```
-
-### Non-JSON Response (XML, plain text, etc.)
-
-For non-JSON responses, use custom response handlers:
-
-```typescript
-import { webhook } from '@versori/run';
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const xmlWebhook = webhook('xml-webhook', {
-  response: {
-    mode: 'sync',
-    onSuccess: ctx =>
-      new Response(ctx.data, {
-        status: 200,
-        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
-      }),
-    onError: ctx =>
-      new Response(ctx.data, {
-        status: 401,
-        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
-      }),
-  },
-})
-  .then(async ctx => {
-    // Create validator
-    const { log } = ctx;  // Versori native log
-    const logger = toStructuredLogger(log, {
-      service: 'webhook-validation',
-    });
-    const validator = new WebhookValidationService({ strictValidation: true }, logger);
-
-    // Extract raw body and public key
-    const rawBody = await ctx.request.text(); // Versori v0.2.29+
-    const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
-
-    // Validate
-    const req = ctx.request();
-    const headers = req?.headers || {};
-    const result = await validator.validateWebhook(rawBody, headers, publicKey);
-
-    if (!result.isValid) {
-      throw new Error('Invalid signature');
-    }
-
-    // Return XML response
-    return '<?xml version="1.0"?><response><status>success</status></response>';
-  })
-  .catch(({ error }) => {
-    // Return XML error
-    return `<?xml version="1.0"?><response><status>error</status><message>${error.message}</message></response>`;
-  });
-```
-
-See [Versori Webhook Response Patterns](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv) for complete documentation.
-
----
-
-## Testing Versori Webhooks
-
-### Local Testing Setup
-
-```typescript
-// test-webhook-locally.ts
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-async function testVersoriWebhook() {
-  // Simulate Versori context
-  const mockContext = {
-    data: {
-      eventId: 'evt_test_123',
-      entityType: 'ORDER',
-      entityId: 'order_456',
-    },
-    headers: {
-      'fluent-signature': 'YOUR_TEST_SIGNATURE',
-      'content-type': 'application/json',
-    },
-    vars: {
-      FLUENT_WEBHOOK_PUBLIC_KEY: process.env.FLUENT_WEBHOOK_PUBLIC_KEY!,
-    },
-    request: {
-      text: async () =>
-        JSON.stringify({
-          eventId: 'evt_test_123',
-          entityType: 'ORDER',
-          entityId: 'order_456',
-        }),
-    },
-    log: console.log,
-    activation: {
-      id: 'test-activation',
-      workflowId: 'test-workflow',
-    },
-  };
-
-  // Test validation
-  const logger = toStructuredLogger(mockContext.log, {
-    service: 'test',
-  });
-  const validator = new WebhookValidationService({ strictValidation: true }, logger);
-
-  const rawBody = await mockContext.request.text();
-  const result = await validator.validateWebhook(
-    rawBody,
-    mockContext.headers,
-    mockContext.vars.FLUENT_WEBHOOK_PUBLIC_KEY
-  );
-
-  console.log('Test result:', result);
-}
-
-testVersoriWebhook();
-```
-
-### Versori Deploy & Test
-
-```bash
-# Deploy to Versori
-npm run deploy
-
-# Get webhook URL from Versori dashboard
-# Example: https://yourspace.versori.run/webhooks/fluent-webhook
-
-# Test with curl (get real signature from Fluent test environment)
-curl -X POST https://yourspace.versori.run/webhooks/fluent-webhook \
-  -H "Content-Type: application/json" \
-  -H "fluent-signature: REAL_SIGNATURE_FROM_FLUENT" \
-  -d '{"eventId":"evt_123","entityType":"ORDER","entityId":"order_456"}'
-
-# Check Versori logs
-npm run logs
-```
-
----
-
-## Versori-Specific Edge Cases
-
-### Edge Case 1: Missing Request Object (Old Versori)
-
-```typescript
-// Handle gracefully when ctx.request is undefined
-const rawBody =
-  ctx.request && typeof ctx.request.text === 'function'
-    ? await ctx.request.text()
-    : JSON.stringify(ctx.data); // Fallback for old versions
-```
-
-### Edge Case 2: Headers Case Sensitivity
-
-```typescript
-// Versori may normalize header names to lowercase
-const req = ctx.request();
-const headers = req?.headers || {};
-const signature =
-  headers['fluent-signature'] || headers['Fluent-Signature'] || headers['FLUENT-SIGNATURE'];
-
-// SDK handles this internally, but be aware for custom logic
-```
-
-### Edge Case 3: Empty Body
-
-```typescript
-// Handle webhooks with empty or null body
-const rawBody =
-  ctx.request && typeof ctx.request.text === 'function'
-    ? await ctx.request.text()
-    : ctx.data
-      ? JSON.stringify(ctx.data)
-      : '{}';
-
-if (!rawBody || rawBody === '{}') {
-  logger.warn('Received webhook with empty body');
-  return { statusCode: 400, body: 'Empty webhook body' };
-}
-```
-
----
-
-## Key Takeaways
-
-- **Use ctx.request.text()** for raw body in Versori v0.2.29+ (fallback to JSON.stringify for older versions)
-- **Store public keys** in Versori variables as secrets
-- **Version-aware code** handles both old and new Versori platforms
-- **Validate before processing** - always check signature before business logic
-- **Use workflow functions** - chain validation → processing for clean separation
-- **Handle errors gracefully** - return proper HTTP status codes for validation failures
-
----
-
-## Practice Exercise
-
-Create a Versori webhook connector that:
-
-1. Validates incoming Fluent Commerce webhooks
-2. Handles both SHA512 and MD5 signatures
-3. Logs validation results
-4. Processes valid webhooks
-5. Returns appropriate HTTP status codes
-
-<details>
-<summary>Solution</summary>
-
-```typescript
-import { webhook, fn } from '@versori/run';
-import {
-  WebhookValidationService,
-  createConsoleLogger,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const practiceWebhook = webhook('practice-webhook')
-  .then(
-    fn('validate', async ctx => {
-      const { log } = ctx;  // Versori native log
-      const logger = toStructuredLogger(log, {
-        service: 'practice',
-      });
-      const validator = new WebhookValidationService({ strictValidation: true }, logger);
-
-      const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
-      if (!publicKey) throw new Error('Missing public key');
-
-      const rawBody = await ctx.request.text(); // Versori v0.2.29+
-      const req = ctx.request();
-      const headers = req?.headers || {};
-      const result = await validator.validateWebhook(rawBody, headers, publicKey);
-
-      if (!result.isValid) {
-        throw new Error(`Validation failed: ${result.error}`);
-      }
-
-      logger.info('Validated with algorithm', { algorithm: result.algorithm });
-      return { ...ctx, data: JSON.parse(rawBody) };
-    })
-  )
-  .then(
-    fn('process', async ctx => {
-      ctx.log('Processing webhook', ctx.data.eventId);
-      // Your processing logic
-      return { success: true, eventId: ctx.data.eventId };
-    })
-  )
-  .catch(({ error }) => ({
-    statusCode: error.message.includes('Validation failed') ? 401 : 500,
-    body: { error: error.message },
-  }));
-```
-
-</details>
-
----
-
-## Next Steps
-
-Continue to [Module 4: Platform Integration](./webhook-validation-04-platform-integration.md) to learn how to integrate webhook validation with Express.js, Next.js, AWS Lambda, and other platforms.
-
----
-
-## Further Reading
-
-- [Versori Webhook Response Patterns](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv) - Complete guide to Versori response handling
-- [Module 5: Configuration](./webhook-validation-05-configuration.md) - Advanced configuration options
-- [Module 6: Error Handling](./webhook-validation-06-error-handling.md) - Comprehensive error handling
+# Module 3: Versori Integration
+
+**Level:** Intermediate
+**Estimated Time:** 25 minutes
+
+## Overview
+
+This module covers **Fluent webhook signature validation** integration with the Versori platform.
+
+**IMPORTANT DISTINCTION**: This is about validating **Fluent Commerce webhook signatures** (cryptographic verification), which is DIFFERENT from **Versori webhook authentication** (platform-level connection-based auth). You'll learn how to validate Fluent webhooks in Versori webhook handlers, access public keys from Versori variables, handle raw body extraction, and implement production-ready Versori webhook connectors.
+
+## Learning Objectives
+
+By the end of this module, you will:
+
+- Understand the difference between Versori webhook auth and Fluent signature validation
+- Integrate Fluent signature validation in Versori webhook handlers
+- Access public keys from Versori variables
+- Handle raw body extraction across Versori versions
+- Implement complete Versori webhook connectors with validation
+- Handle Versori-specific edge cases
+
+---
+
+## Versori Webhook Auth vs Fluent Signature Validation
+
+**CRITICAL DISTINCTION** - These are TWO DIFFERENT security mechanisms:
+
+### Versori Webhook Authentication (Platform-Level)
+
+**Purpose**: Verify webhook caller is authorized to trigger your Versori workflow
+**Mechanism**: Connection-based authentication parameter
+**Configuration**: `webhook('name', { connection: 'conn-name' })`
+**Validation**: Versori platform validates BEFORE your code runs
+**Use Case**: Restrict who can call your webhook endpoint
+
+```typescript
+// ✅ Versori webhook auth (platform validates caller)
+export const myWebhook = webhook('my-webhook', {
+  connection: 'my-connection'  // Platform-level auth
+}, async (ctx) => {
+  // Only runs if caller authenticated via connection
+});
+```
+
+### Fluent Signature Validation (Application-Level)
+
+**Purpose**: Verify webhook payload came from Fluent Commerce and wasn't tampered with
+**Mechanism**: Cryptographic signature verification (HMAC-SHA256/SHA512)
+**Configuration**: Use `WebhookValidationService` in your code
+**Validation**: YOUR code validates using Fluent's public key
+**Use Case**: Verify webhook content authenticity and integrity
+
+```typescript
+// ✅ Fluent signature validation (your code validates content)
+export const fluentWebhook = webhook('fluent-webhook', async (ctx) => {
+  const { log } = ctx;  // Versori native log
+  const logger = toStructuredLogger(log, { service: 'webhook-validation' });
+  const validator = new WebhookValidationService({ strictValidation: true }, logger);
+  const result = await validator.validateWebhook(rawBody, headers, publicKey);
+  // Only process if Fluent signature is valid
+});
+```
+
+### When to Use Which?
+
+| Scenario | Versori Auth | Fluent Validation |
+|----------|-------------|-------------------|
+| **Public webhook from Fluent** | ❌ Not needed | ✅ Required |
+| **Restricted webhook access** | ✅ Recommended | ✅ Also use |
+| **Verify payload integrity** | ❌ Doesn't check | ✅ Required |
+| **Multi-source webhooks** | ✅ Per-source | ✅ Per-source |
+
+**Best Practice**: Use BOTH for Fluent webhooks:
+1. **Versori auth** restricts WHO can call your endpoint
+2. **Fluent validation** verifies WHAT content is authentic
+
+---
+
+## Versori Webhook Pattern
+
+### Complete Versori Webhook with Validation
+
+```typescript
+import { webhook } from '@versori/run';
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const fluentWebhook = webhook('fluent-webhook', async ctx => {
+  // 1. Wrap Versori native log for SDK services
+  const { log } = ctx;  // Versori native log
+  const structuredLogger = toStructuredLogger(log, {
+    service: 'webhook-validation',
+  });
+
+  // Why wrap? SDK services expect StructuredLogger interface with:
+  // - debug(), info(), warn(), error() methods
+  // - Context object with service/module/correlationId
+  // - Native Versori log provides basic methods but no context
+
+  // 2. Create validator (requires StructuredLogger)
+  const validator = new WebhookValidationService(
+    {
+      strictValidation: true,
+    },
+    structuredLogger  // Must be StructuredLogger, not native log
+  );
+
+  // 3. Get public key from Versori variables
+  const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
+  if (!publicKey) {
+    structuredLogger.error('Missing public key in Versori variables');
+    return { statusCode: 500, body: 'Server configuration error' };
+  }
+
+  // 4. Extract raw body (version-aware)
+  const rawBody =
+    ctx.request && typeof ctx.request.text === 'function'
+      ? await ctx.request.text() // Versori v0.2.29+
+      : JSON.stringify(ctx.data); // Older versions
+
+  // 5. Validate webhook
+  const req = ctx.request();
+  const headers = req?.headers || {};
+  const result = await validator.validateWebhook(rawBody, headers, publicKey);
+
+  // 6. Handle invalid signature
+  if (!result.isValid) {
+    structuredLogger.warn('Invalid webhook signature', {
+      error: result.error,
+      algorithm: result.algorithm,
+    });
+    return { statusCode: 401, body: 'Invalid signature' };
+  }
+
+  // 7. Process valid webhook
+  structuredLogger.info('Valid webhook received', { algorithm: result.algorithm });
+  const data = JSON.parse(rawBody);
+
+  // Your business logic here
+  await processFluentWebhook(data);
+
+  return { statusCode: 200, body: 'Success' };
+});
+```
+
+---
+
+## Versori Context Object
+
+### Understanding ctx Object
+
+Versori provides a rich context object to webhook handlers:
+
+```typescript
+interface VersoriWebhookContext {
+  // Request data
+  data: any; // Parsed JSON body
+  headers: Record<string, string>; // Request headers
+  request?: Request; // Raw Request object (v0.2.29+)
+
+  // Versori variables
+  vars: Record<string, string>; // Environment variables
+
+  // Logging
+  log: (message: string, ...args: any[]) => void;
+
+  // Other Versori utilities
+  activation: {
+    id: string;
+    workflowId: string;
+    // ... more activation metadata
+  };
+}
+```
+
+### Accessing Components
+
+```typescript
+export const myWebhook = webhook('my-webhook', async ctx => {
+  // Parsed data (already JSON parsed by Versori)
+  const eventId = ctx.data.eventId;
+
+  // Headers
+  const req = ctx.request();
+  const signature = req?.headers['fluent-signature'] as string;
+
+  // Environment variables
+  const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
+  const env = ctx.vars.ENVIRONMENT;
+
+  // Logging
+  ctx.log('Processing webhook', eventId);
+
+  // Activation metadata
+  const workflowId = ctx.activation.workflowId;
+});
+```
+
+---
+
+## Raw Body Extraction
+
+### Version-Aware Raw Body Extraction
+
+Versori changed how raw bodies are accessed in version 0.2.29:
+
+```typescript
+/**
+ * Extract raw request body - handles both old and new Versori versions
+ */
+async function getRawBody(ctx: any): Promise<string> {
+  // Versori v0.2.29+ provides Request object with text() method
+  if (ctx.request && typeof ctx.request.text === 'function') {
+    return await ctx.request.text();
+  }
+
+  // Older Versori versions - reconstruct from parsed data
+  if (ctx.data) {
+    return JSON.stringify(ctx.data);
+  }
+
+  throw new Error('Unable to extract raw body from context');
+}
+
+// Usage in webhook
+export const myWebhook = webhook('my-webhook', async ctx => {
+  const rawBody = await getRawBody(ctx); // Works across versions
+  // ... validate with rawBody
+});
+```
+
+### Why Raw Body Matters
+
+```typescript
+// ❌ WRONG - Using pre-parsed data
+const rawBody = JSON.stringify(ctx.data);
+// Problem: JSON.stringify may reorder keys, change whitespace
+// This breaks signature verification
+
+// ✅ CORRECT - Use original raw body
+const rawBody = await ctx.request.text();
+// This preserves exact byte sequence for signature verification
+```
+
+**Best Practice**: Always use `ctx.request.text()` when available (Versori v0.2.29+). For older versions, `JSON.stringify(ctx.data)` is acceptable but may have edge cases.
+
+---
+
+## Versori Variables for Public Keys
+
+### Setting Up Versori Variables
+
+In Versori platform UI:
+
+1. Navigate to your workflow
+2. Go to **Variables** tab
+3. Add variable: `FLUENT_WEBHOOK_PUBLIC_KEY`
+4. Set value to your Fluent Commerce public key
+5. Mark as **Secret** for security
+
+```typescript
+// Access in webhook handler
+const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
+```
+
+### Multiple Environment Keys
+
+For workflows that handle multiple environments (prod/sandbox):
+
+```typescript
+// Set multiple variables in Versori
+// FLUENT_WEBHOOK_PUBLIC_KEY_PROD
+// FLUENT_WEBHOOK_PUBLIC_KEY_SANDBOX
+
+// Access based on environment
+export const myWebhook = webhook('my-webhook', async ctx => {
+  const env = ctx.vars.ENVIRONMENT || 'production';
+
+  const publicKey =
+    env === 'production'
+      ? ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY_PROD
+      : ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY_SANDBOX;
+
+  if (!publicKey) {
+    throw new Error(`Missing public key for environment: ${env}`);
+  }
+
+  // ... validate with environment-specific key
+});
+```
+
+---
+
+## Complete Versori Connector Example
+
+### Production-Ready Webhook Connector
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import {
+  WebhookValidationService,
+  WebhookValidationResult,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Fluent Commerce webhook handler with validation
+ */
+export const fluentOrderWebhook = webhook('fluent-order-webhook')
+  .then(
+    fn('validate', async ctx => {
+      // Initialize services
+      const { log } = ctx;  // Versori native log
+      const logger = toStructuredLogger(log, {
+        service: 'webhook-validator',
+      });
+
+      // Get configuration
+      const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
+      if (!publicKey) {
+        throw new Error('FLUENT_WEBHOOK_PUBLIC_KEY not configured in Versori variables');
+      }
+
+      // Extract raw body
+      const rawBody =
+        ctx.request && typeof ctx.request.text === 'function'
+          ? await ctx.request.text()
+          : JSON.stringify(ctx.data);
+
+      // Create validator
+      const validator = new WebhookValidationService(
+        {
+          strictValidation: true,
+        },
+        logger
+      );
+
+      // Validate signature
+      const req = ctx.request();
+      const headers = req?.headers || {};
+      const result: WebhookValidationResult = await validator.validateWebhook(
+        rawBody,
+        headers,
+        publicKey
+      );
+
+      // Handle validation failure
+      if (!result.isValid) {
+        logger.error('Webhook validation failed', {
+          error: result.error,
+          algorithm: result.algorithm,
+          workflowId: ctx.activation.workflowId,
+          headers: Object.keys(headers),
+        });
+
+        throw new Error(`Invalid webhook signature: ${result.error}`);
+      }
+
+      // Log successful validation
+      logger.info('Webhook validated successfully', {
+        algorithm: result.algorithm,
+        timestamp: result.timestamp,
+        workflowId: ctx.activation.workflowId,
+      });
+
+      // Parse and return data
+      const webhookData = JSON.parse(rawBody);
+      return {
+        ...ctx,
+        data: webhookData,
+        validationResult: result,
+      };
+    })
+  )
+  .then(
+    fn('processOrder', async ctx => {
+      // Access validated webhook data
+      const { eventId, entityType, entityId, data } = ctx.data;
+
+      ctx.log('Processing validated webhook', {
+        eventId,
+        entityType,
+        entityId,
+      });
+
+      // Your business logic here
+      if (entityType === 'ORDER') {
+        await processOrder(data);
+      }
+
+      return {
+        success: true,
+        eventId,
+        processedAt: new Date().toISOString(),
+      };
+    })
+  )
+  .catch(({ error, data }) => {
+    // Handle validation or processing errors
+    console.error('Webhook processing failed', { error });
+
+    return {
+      success: false,
+      error: error.message,
+      timestamp: new Date().toISOString(),
+    };
+  });
+
+// Helper function
+async function processOrder(orderData: any): Promise<void> {
+  // Your order processing logic
+  console.log('Processing order:', orderData.ref);
+}
+```
+
+---
+
+## Versori Response Patterns
+
+### Standard JSON Response
+
+```typescript
+export const webhook1 = webhook('webhook1', async ctx => {
+  const req = ctx.request();
+  const headers = req?.headers || {};
+  const result = await validator.validateWebhook(rawBody, headers, publicKey);
+
+  if (!result.isValid) {
+    return {
+      statusCode: 401,
+      body: { error: 'Invalid signature', details: result.error },
+    };
+  }
+
+  return {
+    statusCode: 200,
+    body: { success: true, eventId: ctx.data.eventId },
+  };
+});
+```
+
+### Custom Response Headers
+
+```typescript
+export const webhook2 = webhook('webhook2', async ctx => {
+  const req = ctx.request();
+  const headers = req?.headers || {};
+  const result = await validator.validateWebhook(rawBody, headers, publicKey);
+
+  if (!result.isValid) {
+    return {
+      statusCode: 401,
+      headers: { 'X-Validation-Error': result.error },
+      body: 'Unauthorized',
+    };
+  }
+
+  return {
+    statusCode: 200,
+    headers: { 'X-Validation-Algorithm': result.algorithm },
+    body: 'Success',
+  };
+});
+```
+
+### Non-JSON Response (XML, plain text, etc.)
+
+For non-JSON responses, use custom response handlers:
+
+```typescript
+import { webhook } from '@versori/run';
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const xmlWebhook = webhook('xml-webhook', {
+  response: {
+    mode: 'sync',
+    onSuccess: ctx =>
+      new Response(ctx.data, {
+        status: 200,
+        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+      }),
+    onError: ctx =>
+      new Response(ctx.data, {
+        status: 401,
+        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+      }),
+  },
+})
+  .then(async ctx => {
+    // Create validator
+    const { log } = ctx;  // Versori native log
+    const logger = toStructuredLogger(log, {
+      service: 'webhook-validation',
+    });
+    const validator = new WebhookValidationService({ strictValidation: true }, logger);
+
+    // Extract raw body and public key
+    const rawBody = await ctx.request.text(); // Versori v0.2.29+
+    const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
+
+    // Validate
+    const req = ctx.request();
+    const headers = req?.headers || {};
+    const result = await validator.validateWebhook(rawBody, headers, publicKey);
+
+    if (!result.isValid) {
+      throw new Error('Invalid signature');
+    }
+
+    // Return XML response
+    return '<?xml version="1.0"?><response><status>success</status></response>';
+  })
+  .catch(({ error }) => {
+    // Return XML error
+    return `<?xml version="1.0"?><response><status>error</status><message>${error.message}</message></response>`;
+  });
+```
+
+See [Versori Webhook Response Patterns](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv) for complete documentation.
+
+---
+
+## Testing Versori Webhooks
+
+### Local Testing Setup
+
+```typescript
+// test-webhook-locally.ts
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+async function testVersoriWebhook() {
+  // Simulate Versori context
+  const mockContext = {
+    data: {
+      eventId: 'evt_test_123',
+      entityType: 'ORDER',
+      entityId: 'order_456',
+    },
+    headers: {
+      'fluent-signature': 'YOUR_TEST_SIGNATURE',
+      'content-type': 'application/json',
+    },
+    vars: {
+      FLUENT_WEBHOOK_PUBLIC_KEY: process.env.FLUENT_WEBHOOK_PUBLIC_KEY!,
+    },
+    request: {
+      text: async () =>
+        JSON.stringify({
+          eventId: 'evt_test_123',
+          entityType: 'ORDER',
+          entityId: 'order_456',
+        }),
+    },
+    log: console.log,
+    activation: {
+      id: 'test-activation',
+      workflowId: 'test-workflow',
+    },
+  };
+
+  // Test validation
+  const logger = toStructuredLogger(mockContext.log, {
+    service: 'test',
+  });
+  const validator = new WebhookValidationService({ strictValidation: true }, logger);
+
+  const rawBody = await mockContext.request.text();
+  const result = await validator.validateWebhook(
+    rawBody,
+    mockContext.headers,
+    mockContext.vars.FLUENT_WEBHOOK_PUBLIC_KEY
+  );
+
+  console.log('Test result:', result);
+}
+
+testVersoriWebhook();
+```
+
+### Versori Deploy & Test
+
+```bash
+# Deploy to Versori
+npm run deploy
+
+# Get webhook URL from Versori dashboard
+# Example: https://yourspace.versori.run/webhooks/fluent-webhook
+
+# Test with curl (get real signature from Fluent test environment)
+curl -X POST https://yourspace.versori.run/webhooks/fluent-webhook \
+  -H "Content-Type: application/json" \
+  -H "fluent-signature: REAL_SIGNATURE_FROM_FLUENT" \
+  -d '{"eventId":"evt_123","entityType":"ORDER","entityId":"order_456"}'
+
+# Check Versori logs
+npm run logs
+```
+
+---
+
+## Versori-Specific Edge Cases
+
+### Edge Case 1: Missing Request Object (Old Versori)
+
+```typescript
+// Handle gracefully when ctx.request is undefined
+const rawBody =
+  ctx.request && typeof ctx.request.text === 'function'
+    ? await ctx.request.text()
+    : JSON.stringify(ctx.data); // Fallback for old versions
+```
+
+### Edge Case 2: Headers Case Sensitivity
+
+```typescript
+// Versori may normalize header names to lowercase
+const req = ctx.request();
+const headers = req?.headers || {};
+const signature =
+  headers['fluent-signature'] || headers['Fluent-Signature'] || headers['FLUENT-SIGNATURE'];
+
+// SDK handles this internally, but be aware for custom logic
+```
+
+### Edge Case 3: Empty Body
+
+```typescript
+// Handle webhooks with empty or null body
+const rawBody =
+  ctx.request && typeof ctx.request.text === 'function'
+    ? await ctx.request.text()
+    : ctx.data
+      ? JSON.stringify(ctx.data)
+      : '{}';
+
+if (!rawBody || rawBody === '{}') {
+  logger.warn('Received webhook with empty body');
+  return { statusCode: 400, body: 'Empty webhook body' };
+}
+```
+
+---
+
+## Key Takeaways
+
+- **Use ctx.request.text()** for raw body in Versori v0.2.29+ (fallback to JSON.stringify for older versions)
+- **Store public keys** in Versori variables as secrets
+- **Version-aware code** handles both old and new Versori platforms
+- **Validate before processing** - always check signature before business logic
+- **Use workflow functions** - chain validation → processing for clean separation
+- **Handle errors gracefully** - return proper HTTP status codes for validation failures
+
+---
+
+## Practice Exercise
+
+Create a Versori webhook connector that:
+
+1. Validates incoming Fluent Commerce webhooks
+2. Handles both SHA512 and MD5 signatures
+3. Logs validation results
+4. Processes valid webhooks
+5. Returns appropriate HTTP status codes
+
+<details>
+<summary>Solution</summary>
+
+```typescript
+import { webhook, fn } from '@versori/run';
+import {
+  WebhookValidationService,
+  createConsoleLogger,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const practiceWebhook = webhook('practice-webhook')
+  .then(
+    fn('validate', async ctx => {
+      const { log } = ctx;  // Versori native log
+      const logger = toStructuredLogger(log, {
+        service: 'practice',
+      });
+      const validator = new WebhookValidationService({ strictValidation: true }, logger);
+
+      const publicKey = ctx.vars.FLUENT_WEBHOOK_PUBLIC_KEY;
+      if (!publicKey) throw new Error('Missing public key');
+
+      const rawBody = await ctx.request.text(); // Versori v0.2.29+
+      const req = ctx.request();
+      const headers = req?.headers || {};
+      const result = await validator.validateWebhook(rawBody, headers, publicKey);
+
+      if (!result.isValid) {
+        throw new Error(`Validation failed: ${result.error}`);
+      }
+
+      logger.info('Validated with algorithm', { algorithm: result.algorithm });
+      return { ...ctx, data: JSON.parse(rawBody) };
+    })
+  )
+  .then(
+    fn('process', async ctx => {
+      ctx.log('Processing webhook', ctx.data.eventId);
+      // Your processing logic
+      return { success: true, eventId: ctx.data.eventId };
+    })
+  )
+  .catch(({ error }) => ({
+    statusCode: error.message.includes('Validation failed') ? 401 : 500,
+    body: { error: error.message },
+  }));
+```
+
+</details>
+
+---
+
+## Next Steps
+
+Continue to [Module 4: Platform Integration](./webhook-validation-04-platform-integration.md) to learn how to integrate webhook validation with Express.js, Next.js, AWS Lambda, and other platforms.
+
+---
+
+## Further Reading
+
+- [Versori Webhook Response Patterns](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv) - Complete guide to Versori response handling
+- [Module 5: Configuration](./webhook-validation-05-configuration.md) - Advanced configuration options
+- [Module 6: Error Handling](./webhook-validation-06-error-handling.md) - Comprehensive error handling