@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-08-rubix-webhooks.md

@@ -1,590 +1,590 @@
-# Module 8: Rubix Webhook Validation
-
-**Level:** Intermediate
-**Estimated Time:** 20 minutes
-
-## Overview
-
-This module covers webhook signature validation for **Fluent Commerce Rubix HTTP Call webhooks** - a specific use case different from Fluent Commerce Event webhooks.
-
-**CRITICAL DISTINCTION**: This guide is for validating webhooks sent from **Rubix workflows** using the **HTTP Call action**, which have a different payload structure than Fluent Commerce Event webhooks.
-
-## Learning Objectives
-
-By the end of this module, you will:
-
-- Understand the difference between Rubix HTTP Call webhooks and Event webhooks
-- Know which validation method to use for each webhook type
-- Implement correct signature validation for Rubix workflows
-- Configure Rubix workflows to send properly signed webhooks
-- Handle signature validation in Versori webhook handlers
-
----
-
-## Rubix HTTP Call vs Event Webhooks
-
-### Two Types of Fluent Commerce Webhooks
-
-Fluent Commerce has **TWO different webhook types** with different payload structures:
-
-| Feature | Rubix HTTP Call Webhooks | Event Webhooks |
-|---------|-------------------------|----------------|
-| **Trigger** | Rubix workflow HTTP Call action | Fluent Commerce event system |
-| **Payload Structure** | Custom (entityId, entityRef, etc.) | Standard (name, id, retailerId, etc.) |
-| **Use Case** | Custom workflow integrations | Event-driven integrations |
-| **Validation Method** | ✅ `WebhookValidationService` | ✅ `FluentClient.validateWebhook()` |
-| **Signature Headers** | `fluent-signature`, `flex.signature` | `fluent-signature`, `flex.signature` |
-| **Public Key Required** | Yes (x509 base64) | Yes (x509 base64) |
-
-### Rubix HTTP Call Webhook Payload
-
-```json
-{
-  "entityId": "order-123",
-  "entityRef": "ORD-001",
-  "entityType": "order",
-  "triggerSource": "ORDER_FULFILLMENT",
-  "retailerId": "1",
-  "timestamp": "2025-11-07T12:34:56.789Z"
-}
-```
-
-### Event Webhook Payload
-
-```json
-{
-  "name": "ORDER.CREATED",
-  "id": "evt-123",
-  "retailerId": "1",
-  "entityId": "order-123",
-  "entityType": "ORDER",
-  "timestamp": "2025-11-07T12:34:56.789Z",
-  "data": { /* event data */ }
-}
-```
-
-**Key Difference**: Rubix webhooks have custom payload structure, Event webhooks have standardized fields (`name`, `id`, `retailerId`).
-
----
-
-## Which Validation Method to Use?
-
-### ✅ Use WebhookValidationService for Rubix HTTP Calls
-
-```typescript
-import { WebhookValidationService } from '@fluentcommerce/fc-connect-sdk';
-
-// ✅ CORRECT for Rubix HTTP Call webhooks
-// Versori log can be passed directly (no wrapper needed)
-const validator = new WebhookValidationService({ strictValidation: true }, log);
-
-const result = await validator.validateWebhook(
-  rawBodyString,  // Raw payload string
-  headers,        // Headers object
-  publicKey       // x509 base64 public key
-);
-```
-
-**Why**: `WebhookValidationService` validates the signature without requiring specific payload fields.
-
-### ✅ Use FluentClient.validateWebhook() for Event Webhooks
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// ✅ CORRECT for Fluent Commerce Event webhooks
-const client = await createClient({ ...ctx, log, connections });
-
-const isValid = await client.validateWebhook(
-  payload,      // FluentWebhookPayload object (must have name, id, retailerId)
-  signature,    // Signature string
-  rawPayload    // Raw payload string
-);
-```
-
-**Why**: `FluentClient.validateWebhook()` does additional field validation for Event webhooks.
-
-### ❌ Common Mistake: Using Wrong Method
-
-```typescript
-// ❌ WRONG - Using FluentClient.validateWebhook() for Rubix webhooks
-const client = await createClient({ ...ctx, log });
-const isValid = await client.validateWebhook(
-  rubixPayload,  // ❌ Rubix payload doesn't have name, id, retailerId
-  signature,
-  rawPayload
-);
-// Result: Always returns false (fails basic field validation)
-```
-
----
-
-## Rubix Webhook Validation Pattern
-
-### Complete Implementation
-
-```typescript
-import { webhook, http } from '@versori/run';
-import {
-  createClient,
-  WebhookValidationService,
-  toStructuredLogger,
-} from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * Rubix HTTP Call Webhook Handler with Signature Validation
- */
-export const rubixWebhook = webhook('rubix-webhook', {
-  response: { mode: 'sync' },
-}).then(
-  http('validate-and-process', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, activation, connections } = ctx;
-
-    try {
-      // =========================================================
-      // STEP 1: VALIDATE WEBHOOK SIGNATURE
-      // =========================================================
-
-      // Get public key (x509 base64 encoded)
-      const publicKey = activation.getVariable('fluentPublicKey');
-      if (!publicKey) {
-        log.error('Missing fluentPublicKey activation variable');
-        return {
-          status: 500,
-          body: { error: 'Missing public key configuration' }
-        };
-      }
-
-      // Get raw payload (must be raw string, not parsed)
-      const rawPayload = activation.body || ctx.data;
-      const rawBodyString = typeof rawPayload === 'string'
-        ? rawPayload
-        : JSON.stringify(rawPayload);
-
-      // Get headers
-      const headers = activation.headers || {};
-
-      // Check for signature headers
-      const hasSignature = !!(
-        headers['fluent-signature'] ||
-        headers['x-fluent-signature'] ||
-        headers['flex.signature']
-      );
-
-      if (hasSignature) {
-        // Create validator (Versori log can be passed directly)
-        const validator = new WebhookValidationService(
-          { strictValidation: true },
-          log
-        );
-
-        // Validate signature
-        // Auto-detects: fluent-signature (SHA512) preferred, flex.signature (MD5) fallback
-        const result = await validator.validateWebhook(
-          rawBodyString,  // Raw payload string
-          headers,        // Headers object
-          publicKey       // x509 base64 public key
-        );
-
-        if (!result.isValid) {
-          log.error('Invalid webhook signature', {
-            error: result.error,
-            algorithm: result.algorithm,
-          });
-          return {
-            status: 401,
-            body: { error: 'Invalid signature' }
-          };
-        }
-
-        log.info('✅ Webhook signature validated', {
-          algorithm: result.algorithm,
-        });
-      } else {
-        log.warn('No signature header found - skipping validation');
-      }
-
-      // Parse payload (AFTER validation)
-      const payload = typeof rawPayload === 'string'
-        ? JSON.parse(rawPayload)
-        : rawPayload;
-
-      // =========================================================
-      // STEP 2: EXTRACT ENTITY INFORMATION
-      // =========================================================
-
-      const { entityId, entityRef, entityType, retailerId } = payload;
-
-      if (!entityId && !entityRef) {
-        log.error('Missing entity identifier');
-        return {
-          status: 400,
-          body: { error: 'Missing entityId or entityRef' }
-        };
-      }
-
-      log.info('Processing Rubix webhook', {
-        entityId,
-        entityRef,
-        entityType,
-      });
-
-      // =========================================================
-      // STEP 3: QUERY FLUENT FOR ENTITY DETAILS
-      // =========================================================
-
-      const fluentClient = await createClient({
-        ...ctx,
-        log,
-        connections,
-      });
-
-      await fluentClient.setRetailerId(retailerId);
-
-      // Query entity (example: order)
-      const query = `
-        query GetEntity($ref: String!) {
-          order(ref: $ref) {
-            id
-            ref
-            status
-          }
-        }
-      `;
-
-      const result = await fluentClient.graphql({
-        query,
-        variables: { ref: entityRef }
-      });
-
-      if (result.errors?.length) {
-        log.error('GraphQL query failed', { errors: result.errors });
-        return {
-          status: 502,
-          body: { error: 'Failed to fetch entity' }
-        };
-      }
-
-      const entity = result.data?.order;
-
-      // =========================================================
-      // STEP 4: PROCESS ENTITY
-      // =========================================================
-
-      log.info('Entity retrieved', {
-        entityId: entity.id,
-        entityRef: entity.ref,
-        status: entity.status,
-      });
-
-      // Your business logic here
-      await processEntity(entity);
-
-      return {
-        status: 200,
-        body: {
-          success: true,
-          entityId: entity.id,
-          entityRef: entity.ref,
-        }
-      };
-
-    } catch (error: any) {
-      log.error('Webhook processing failed', {
-        error: error.message,
-        stack: error.stack,
-      });
-
-      return {
-        status: 500,
-        body: { error: error.message }
-      };
-    }
-  })
-);
-
-async function processEntity(entity: any): Promise<void> {
-  // Your processing logic
-  console.log('Processing entity:', entity.ref);
-}
-```
-
----
-
-## Configuring Rubix Workflows
-
-### Step 1: Add HTTP Call Action in Rubix
-
-In your Rubix workflow, add an **HTTP Call** action:
-
-**Action Configuration:**
-```
-Method: POST
-URL: https://{workspace}.versori.run/rubix-webhook
-```
-
-**Headers:**
-```json
-{
-  "Content-Type": "application/json",
-  "fluent-signature": "${webhookSignature}",
-  "x-retailer-id": "${retailerId}"
-}
-```
-
-**Payload:**
-```json
-{
-  "entityId": "${entity.id}",
-  "entityRef": "${entity.ref}",
-  "entityType": "order",
-  "retailerId": "${retailerId}",
-  "timestamp": "${currentTimestamp}"
-}
-```
-
-### Step 2: Configure Webhook Signature in Rubix
-
-Fluent Commerce automatically generates signatures using its private key. The signature is available as `${webhookSignature}` in Rubix workflows.
-
-**Important**: The signature is generated server-side by Fluent Commerce. You don't need to generate it manually in Rubix.
-
-### Step 3: Configure Public Key in Versori
-
-In Versori Dashboard → Activation Variables:
-
-```
-fluentPublicKey: MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC5/F8wX0...
-```
-
-**Public Key Sources:**
-- Get from Fluent Commerce dashboard
-- Environment/region-specific (see Fluent Commerce documentation)
-- Format: x509 base64 encoded
-
----
-
-## Signature Algorithm Selection
-
-Fluent Commerce sends **BOTH signature headers** in every webhook:
-
-| Header | Algorithm | Priority | Use Case |
-|--------|-----------|----------|----------|
-| `fluent-signature` | SHA512withRSA | ✅ Preferred | Modern Rubix workflows |
-| `flex.signature` | MD5withRSA | ⚠️ Fallback | Legacy Flex workflows |
-
-**SDK Auto-Detection:**
-```typescript
-// SDK automatically selects the best algorithm:
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-// 1. Tries fluent-signature (SHA512) first
-// 2. Falls back to flex.signature (MD5) if needed
-// 3. Returns result with algorithm used
-```
-
-**Algorithm in Response:**
-```typescript
-if (result.isValid) {
-  console.log(`Validated with ${result.algorithm}`);
-  // Output: "Validated with SHA512withRSA" or "Validated with MD5withRSA"
-}
-```
-
----
-
-## Common Issues and Solutions
-
-### Issue 1: Validation Always Fails
-
-**Symptom**: Every webhook validation returns `isValid: false`
-
-**Possible Causes:**
-
-1. **Wrong Public Key**
-   ```typescript
-   // ✅ Check: Using correct environment's public key?
-   console.log('Public key prefix:', publicKey.substring(0, 30));
-   // Should start with "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBi..."
-   ```
-
-2. **Modified Payload**
-   ```typescript
-   // ❌ WRONG - Modifying payload before validation
-   const rawBody = JSON.stringify(JSON.parse(activation.body));
-
-   // ✅ CORRECT - Use original raw body
-   const rawBody = activation.body; // Keep as-is
-   ```
-
-3. **Missing Signature Header**
-   ```typescript
-   // Check headers
-   console.log('Headers:', Object.keys(headers));
-   console.log('Has fluent-signature:', !!headers['fluent-signature']);
-   ```
-
-### Issue 2: Using FluentClient.validateWebhook() for Rubix
-
-**Symptom**: Validation fails with "missing required fields"
-
-**Cause**: `FluentClient.validateWebhook()` expects Event webhook structure
-
-**Solution**: Use `WebhookValidationService` instead
-
-```typescript
-// ❌ WRONG for Rubix webhooks
-const isValid = await fluentClient.validateWebhook(payload, sig, raw);
-
-// ✅ CORRECT for Rubix webhooks
-const validator = new WebhookValidationService({}, logger);
-const result = await validator.validateWebhook(raw, headers, publicKey);
-```
-
-### Issue 3: Public Key Format Issues
-
-**Symptom**: Cryptographic errors during validation
-
-**Possible Causes:**
-
-1. **Extra whitespace or newlines**
-   ```typescript
-   // ✅ Trim whitespace
-   const publicKey = activation.getVariable('fluentPublicKey').trim();
-   ```
-
-2. **Wrong encoding**
-   ```typescript
-   // ✅ Should be x509 base64 encoded
-   // Format: MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC5/F8wX0...
-   // NOT PEM format with headers (SDK handles conversion if needed)
-   ```
-
-3. **Environment mismatch**
-   ```typescript
-   // ✅ Use correct public key for environment
-   const env = activation.getVariable('environment') || 'production';
-   const publicKey = activation.getVariable(`fluentPublicKey_${env}`);
-   ```
-
----
-
-## Testing Rubix Webhooks
-
-### Local Testing with curl
-
-```bash
-# Generate test payload
-PAYLOAD='{"entityId":"order-123","entityRef":"ORD-001","entityType":"order","retailerId":"1"}'
-
-# Get signature from Fluent Commerce test webhook
-# (Use Rubix test mode to capture real signature)
-
-# Send test request
-curl -X POST https://{workspace}.versori.run/rubix-webhook \
-  -H "Content-Type: application/json" \
-  -H "fluent-signature: {REAL_SIGNATURE_FROM_FLUENT}" \
-  -H "x-retailer-id: 1" \
-  -d "$PAYLOAD"
-```
-
-### Rubix Test Mode
-
-1. Enable test mode in Rubix workflow
-2. Trigger workflow manually
-3. Check Versori logs for validation results
-4. Verify signature validation succeeds
-
----
-
-## Key Takeaways
-
-- **Two webhook types**: Rubix HTTP Calls (custom payload) vs Event webhooks (standard payload)
-- **Rubix validation**: Use `WebhookValidationService` directly
-- **Event validation**: Use `FluentClient.validateWebhook()`
-- **Signature headers**: Fluent sends BOTH (`fluent-signature` and `flex.signature`)
-- **Auto-detection**: SDK automatically selects best algorithm
-- **Raw payload**: Always validate against raw string, not parsed JSON
-- **Public keys**: Environment/region-specific, get from Fluent Commerce
-
----
-
-## Practice Exercise
-
-Create a Rubix webhook handler that:
-1. Validates webhook signature using `WebhookValidationService`
-2. Extracts entity information from custom payload
-3. Queries Fluent GraphQL for entity details
-4. Returns structured response
-
-<details>
-<summary>Solution</summary>
-
-```typescript
-import { webhook, http } from '@versori/run';
-import {
-  createClient,
-  WebhookValidationService,
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const practiceRubixWebhook = webhook('practice-rubix', {
-  response: { mode: 'sync' },
-}).then(
-  http('handler', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, activation, connections } = ctx;
-
-    // Get configuration
-    const publicKey = activation.getVariable('fluentPublicKey');
-    const rawBody = activation.body || JSON.stringify(ctx.data);
-    const headers = activation.headers || {};
-
-    // Validate signature (Versori log can be passed directly)
-    const validator = new WebhookValidationService({ strictValidation: true }, log);
-    const result = await validator.validateWebhook(rawBody, headers, publicKey);
-
-    if (!result.isValid) {
-      return { status: 401, body: { error: result.error } };
-    }
-
-    // Parse payload
-    const payload = JSON.parse(rawBody);
-    const { entityRef, retailerId } = payload;
-
-    // Query Fluent
-    const client = await createClient({ ...ctx, log, connections });
-    await client.setRetailerId(retailerId);
-
-    const queryResult = await client.graphql({
-      query: `query($ref: String!) { order(ref: $ref) { id ref status } }`,
-      variables: { ref: entityRef }
-    });
-
-    const order = queryResult.data?.order;
-
-    return {
-      status: 200,
-      body: {
-        success: true,
-        order: { id: order.id, ref: order.ref, status: order.status }
-      }
-    };
-  })
-);
-```
-
-</details>
-
----
-
-## Next Steps
-
-- Review [Module 3: Versori Integration](./webhook-validation-03-versori-integration.md) for more Versori patterns
-- Check [Rubix Webhook Template](../../../01-TEMPLATES/versori/workflows/rubix-webhooks/template-fluent-rubix-webhook-pattern.md) for production example
-- See [API Reference](./webhook-validation-07-api-reference.md) for complete method signatures
-
----
-
-## Further Reading
-
-- [Fluent Commerce Webhook Documentation](https://docs.fluentcommerce.com/essential-knowledge/webhooks)
-- [Rubix Workflow HTTP Call Action](https://docs.fluentcommerce.com/rubix/workflows/http-call)
-- [Versori Platform Guide](../../../04-REFERENCE/platforms/versori/)
+# Module 8: Rubix Webhook Validation
+
+**Level:** Intermediate
+**Estimated Time:** 20 minutes
+
+## Overview
+
+This module covers webhook signature validation for **Fluent Commerce Rubix HTTP Call webhooks** - a specific use case different from Fluent Commerce Event webhooks.
+
+**CRITICAL DISTINCTION**: This guide is for validating webhooks sent from **Rubix workflows** using the **HTTP Call action**, which have a different payload structure than Fluent Commerce Event webhooks.
+
+## Learning Objectives
+
+By the end of this module, you will:
+
+- Understand the difference between Rubix HTTP Call webhooks and Event webhooks
+- Know which validation method to use for each webhook type
+- Implement correct signature validation for Rubix workflows
+- Configure Rubix workflows to send properly signed webhooks
+- Handle signature validation in Versori webhook handlers
+
+---
+
+## Rubix HTTP Call vs Event Webhooks
+
+### Two Types of Fluent Commerce Webhooks
+
+Fluent Commerce has **TWO different webhook types** with different payload structures:
+
+| Feature | Rubix HTTP Call Webhooks | Event Webhooks |
+|---------|-------------------------|----------------|
+| **Trigger** | Rubix workflow HTTP Call action | Fluent Commerce event system |
+| **Payload Structure** | Custom (entityId, entityRef, etc.) | Standard (name, id, retailerId, etc.) |
+| **Use Case** | Custom workflow integrations | Event-driven integrations |
+| **Validation Method** | ✅ `WebhookValidationService` | ✅ `FluentClient.validateWebhook()` |
+| **Signature Headers** | `fluent-signature`, `flex.signature` | `fluent-signature`, `flex.signature` |
+| **Public Key Required** | Yes (x509 base64) | Yes (x509 base64) |
+
+### Rubix HTTP Call Webhook Payload
+
+```json
+{
+  "entityId": "order-123",
+  "entityRef": "ORD-001",
+  "entityType": "order",
+  "triggerSource": "ORDER_FULFILLMENT",
+  "retailerId": "1",
+  "timestamp": "2025-11-07T12:34:56.789Z"
+}
+```
+
+### Event Webhook Payload
+
+```json
+{
+  "name": "ORDER.CREATED",
+  "id": "evt-123",
+  "retailerId": "1",
+  "entityId": "order-123",
+  "entityType": "ORDER",
+  "timestamp": "2025-11-07T12:34:56.789Z",
+  "data": { /* event data */ }
+}
+```
+
+**Key Difference**: Rubix webhooks have custom payload structure, Event webhooks have standardized fields (`name`, `id`, `retailerId`).
+
+---
+
+## Which Validation Method to Use?
+
+### ✅ Use WebhookValidationService for Rubix HTTP Calls
+
+```typescript
+import { WebhookValidationService } from '@fluentcommerce/fc-connect-sdk';
+
+// ✅ CORRECT for Rubix HTTP Call webhooks
+// Versori log can be passed directly (no wrapper needed)
+const validator = new WebhookValidationService({ strictValidation: true }, log);
+
+const result = await validator.validateWebhook(
+  rawBodyString,  // Raw payload string
+  headers,        // Headers object
+  publicKey       // x509 base64 public key
+);
+```
+
+**Why**: `WebhookValidationService` validates the signature without requiring specific payload fields.
+
+### ✅ Use FluentClient.validateWebhook() for Event Webhooks
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// ✅ CORRECT for Fluent Commerce Event webhooks
+const client = await createClient({ ...ctx, log, connections });
+
+const isValid = await client.validateWebhook(
+  payload,      // FluentWebhookPayload object (must have name, id, retailerId)
+  signature,    // Signature string
+  rawPayload    // Raw payload string
+);
+```
+
+**Why**: `FluentClient.validateWebhook()` does additional field validation for Event webhooks.
+
+### ❌ Common Mistake: Using Wrong Method
+
+```typescript
+// ❌ WRONG - Using FluentClient.validateWebhook() for Rubix webhooks
+const client = await createClient({ ...ctx, log });
+const isValid = await client.validateWebhook(
+  rubixPayload,  // ❌ Rubix payload doesn't have name, id, retailerId
+  signature,
+  rawPayload
+);
+// Result: Always returns false (fails basic field validation)
+```
+
+---
+
+## Rubix Webhook Validation Pattern
+
+### Complete Implementation
+
+```typescript
+import { webhook, http } from '@versori/run';
+import {
+  createClient,
+  WebhookValidationService,
+  toStructuredLogger,
+} from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * Rubix HTTP Call Webhook Handler with Signature Validation
+ */
+export const rubixWebhook = webhook('rubix-webhook', {
+  response: { mode: 'sync' },
+}).then(
+  http('validate-and-process', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, activation, connections } = ctx;
+
+    try {
+      // =========================================================
+      // STEP 1: VALIDATE WEBHOOK SIGNATURE
+      // =========================================================
+
+      // Get public key (x509 base64 encoded)
+      const publicKey = activation.getVariable('fluentPublicKey');
+      if (!publicKey) {
+        log.error('Missing fluentPublicKey activation variable');
+        return {
+          status: 500,
+          body: { error: 'Missing public key configuration' }
+        };
+      }
+
+      // Get raw payload (must be raw string, not parsed)
+      const rawPayload = activation.body || ctx.data;
+      const rawBodyString = typeof rawPayload === 'string'
+        ? rawPayload
+        : JSON.stringify(rawPayload);
+
+      // Get headers
+      const headers = activation.headers || {};
+
+      // Check for signature headers
+      const hasSignature = !!(
+        headers['fluent-signature'] ||
+        headers['x-fluent-signature'] ||
+        headers['flex.signature']
+      );
+
+      if (hasSignature) {
+        // Create validator (Versori log can be passed directly)
+        const validator = new WebhookValidationService(
+          { strictValidation: true },
+          log
+        );
+
+        // Validate signature
+        // Auto-detects: fluent-signature (SHA512) preferred, flex.signature (MD5) fallback
+        const result = await validator.validateWebhook(
+          rawBodyString,  // Raw payload string
+          headers,        // Headers object
+          publicKey       // x509 base64 public key
+        );
+
+        if (!result.isValid) {
+          log.error('Invalid webhook signature', {
+            error: result.error,
+            algorithm: result.algorithm,
+          });
+          return {
+            status: 401,
+            body: { error: 'Invalid signature' }
+          };
+        }
+
+        log.info('✅ Webhook signature validated', {
+          algorithm: result.algorithm,
+        });
+      } else {
+        log.warn('No signature header found - skipping validation');
+      }
+
+      // Parse payload (AFTER validation)
+      const payload = typeof rawPayload === 'string'
+        ? JSON.parse(rawPayload)
+        : rawPayload;
+
+      // =========================================================
+      // STEP 2: EXTRACT ENTITY INFORMATION
+      // =========================================================
+
+      const { entityId, entityRef, entityType, retailerId } = payload;
+
+      if (!entityId && !entityRef) {
+        log.error('Missing entity identifier');
+        return {
+          status: 400,
+          body: { error: 'Missing entityId or entityRef' }
+        };
+      }
+
+      log.info('Processing Rubix webhook', {
+        entityId,
+        entityRef,
+        entityType,
+      });
+
+      // =========================================================
+      // STEP 3: QUERY FLUENT FOR ENTITY DETAILS
+      // =========================================================
+
+      const fluentClient = await createClient({
+        ...ctx,
+        log,
+        connections,
+      });
+
+      await fluentClient.setRetailerId(retailerId);
+
+      // Query entity (example: order)
+      const query = `
+        query GetEntity($ref: String!) {
+          order(ref: $ref) {
+            id
+            ref
+            status
+          }
+        }
+      `;
+
+      const result = await fluentClient.graphql({
+        query,
+        variables: { ref: entityRef }
+      });
+
+      if (result.errors?.length) {
+        log.error('GraphQL query failed', { errors: result.errors });
+        return {
+          status: 502,
+          body: { error: 'Failed to fetch entity' }
+        };
+      }
+
+      const entity = result.data?.order;
+
+      // =========================================================
+      // STEP 4: PROCESS ENTITY
+      // =========================================================
+
+      log.info('Entity retrieved', {
+        entityId: entity.id,
+        entityRef: entity.ref,
+        status: entity.status,
+      });
+
+      // Your business logic here
+      await processEntity(entity);
+
+      return {
+        status: 200,
+        body: {
+          success: true,
+          entityId: entity.id,
+          entityRef: entity.ref,
+        }
+      };
+
+    } catch (error: any) {
+      log.error('Webhook processing failed', {
+        error: error.message,
+        stack: error.stack,
+      });
+
+      return {
+        status: 500,
+        body: { error: error.message }
+      };
+    }
+  })
+);
+
+async function processEntity(entity: any): Promise<void> {
+  // Your processing logic
+  console.log('Processing entity:', entity.ref);
+}
+```
+
+---
+
+## Configuring Rubix Workflows
+
+### Step 1: Add HTTP Call Action in Rubix
+
+In your Rubix workflow, add an **HTTP Call** action:
+
+**Action Configuration:**
+```
+Method: POST
+URL: https://{workspace}.versori.run/rubix-webhook
+```
+
+**Headers:**
+```json
+{
+  "Content-Type": "application/json",
+  "fluent-signature": "${webhookSignature}",
+  "x-retailer-id": "${retailerId}"
+}
+```
+
+**Payload:**
+```json
+{
+  "entityId": "${entity.id}",
+  "entityRef": "${entity.ref}",
+  "entityType": "order",
+  "retailerId": "${retailerId}",
+  "timestamp": "${currentTimestamp}"
+}
+```
+
+### Step 2: Configure Webhook Signature in Rubix
+
+Fluent Commerce automatically generates signatures using its private key. The signature is available as `${webhookSignature}` in Rubix workflows.
+
+**Important**: The signature is generated server-side by Fluent Commerce. You don't need to generate it manually in Rubix.
+
+### Step 3: Configure Public Key in Versori
+
+In Versori Dashboard → Activation Variables:
+
+```
+fluentPublicKey: MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC5/F8wX0...
+```
+
+**Public Key Sources:**
+- Get from Fluent Commerce dashboard
+- Environment/region-specific (see Fluent Commerce documentation)
+- Format: x509 base64 encoded
+
+---
+
+## Signature Algorithm Selection
+
+Fluent Commerce sends **BOTH signature headers** in every webhook:
+
+| Header | Algorithm | Priority | Use Case |
+|--------|-----------|----------|----------|
+| `fluent-signature` | SHA512withRSA | ✅ Preferred | Modern Rubix workflows |
+| `flex.signature` | MD5withRSA | ⚠️ Fallback | Legacy Flex workflows |
+
+**SDK Auto-Detection:**
+```typescript
+// SDK automatically selects the best algorithm:
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+// 1. Tries fluent-signature (SHA512) first
+// 2. Falls back to flex.signature (MD5) if needed
+// 3. Returns result with algorithm used
+```
+
+**Algorithm in Response:**
+```typescript
+if (result.isValid) {
+  console.log(`Validated with ${result.algorithm}`);
+  // Output: "Validated with SHA512withRSA" or "Validated with MD5withRSA"
+}
+```
+
+---
+
+## Common Issues and Solutions
+
+### Issue 1: Validation Always Fails
+
+**Symptom**: Every webhook validation returns `isValid: false`
+
+**Possible Causes:**
+
+1. **Wrong Public Key**
+   ```typescript
+   // ✅ Check: Using correct environment's public key?
+   console.log('Public key prefix:', publicKey.substring(0, 30));
+   // Should start with "MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBi..."
+   ```
+
+2. **Modified Payload**
+   ```typescript
+   // ❌ WRONG - Modifying payload before validation
+   const rawBody = JSON.stringify(JSON.parse(activation.body));
+
+   // ✅ CORRECT - Use original raw body
+   const rawBody = activation.body; // Keep as-is
+   ```
+
+3. **Missing Signature Header**
+   ```typescript
+   // Check headers
+   console.log('Headers:', Object.keys(headers));
+   console.log('Has fluent-signature:', !!headers['fluent-signature']);
+   ```
+
+### Issue 2: Using FluentClient.validateWebhook() for Rubix
+
+**Symptom**: Validation fails with "missing required fields"
+
+**Cause**: `FluentClient.validateWebhook()` expects Event webhook structure
+
+**Solution**: Use `WebhookValidationService` instead
+
+```typescript
+// ❌ WRONG for Rubix webhooks
+const isValid = await fluentClient.validateWebhook(payload, sig, raw);
+
+// ✅ CORRECT for Rubix webhooks
+const validator = new WebhookValidationService({}, logger);
+const result = await validator.validateWebhook(raw, headers, publicKey);
+```
+
+### Issue 3: Public Key Format Issues
+
+**Symptom**: Cryptographic errors during validation
+
+**Possible Causes:**
+
+1. **Extra whitespace or newlines**
+   ```typescript
+   // ✅ Trim whitespace
+   const publicKey = activation.getVariable('fluentPublicKey').trim();
+   ```
+
+2. **Wrong encoding**
+   ```typescript
+   // ✅ Should be x509 base64 encoded
+   // Format: MIGfMA0GCSqGSIb3DQEBAQUAA4GNADCBiQKBgQC5/F8wX0...
+   // NOT PEM format with headers (SDK handles conversion if needed)
+   ```
+
+3. **Environment mismatch**
+   ```typescript
+   // ✅ Use correct public key for environment
+   const env = activation.getVariable('environment') || 'production';
+   const publicKey = activation.getVariable(`fluentPublicKey_${env}`);
+   ```
+
+---
+
+## Testing Rubix Webhooks
+
+### Local Testing with curl
+
+```bash
+# Generate test payload
+PAYLOAD='{"entityId":"order-123","entityRef":"ORD-001","entityType":"order","retailerId":"1"}'
+
+# Get signature from Fluent Commerce test webhook
+# (Use Rubix test mode to capture real signature)
+
+# Send test request
+curl -X POST https://{workspace}.versori.run/rubix-webhook \
+  -H "Content-Type: application/json" \
+  -H "fluent-signature: {REAL_SIGNATURE_FROM_FLUENT}" \
+  -H "x-retailer-id: 1" \
+  -d "$PAYLOAD"
+```
+
+### Rubix Test Mode
+
+1. Enable test mode in Rubix workflow
+2. Trigger workflow manually
+3. Check Versori logs for validation results
+4. Verify signature validation succeeds
+
+---
+
+## Key Takeaways
+
+- **Two webhook types**: Rubix HTTP Calls (custom payload) vs Event webhooks (standard payload)
+- **Rubix validation**: Use `WebhookValidationService` directly
+- **Event validation**: Use `FluentClient.validateWebhook()`
+- **Signature headers**: Fluent sends BOTH (`fluent-signature` and `flex.signature`)
+- **Auto-detection**: SDK automatically selects best algorithm
+- **Raw payload**: Always validate against raw string, not parsed JSON
+- **Public keys**: Environment/region-specific, get from Fluent Commerce
+
+---
+
+## Practice Exercise
+
+Create a Rubix webhook handler that:
+1. Validates webhook signature using `WebhookValidationService`
+2. Extracts entity information from custom payload
+3. Queries Fluent GraphQL for entity details
+4. Returns structured response
+
+<details>
+<summary>Solution</summary>
+
+```typescript
+import { webhook, http } from '@versori/run';
+import {
+  createClient,
+  WebhookValidationService,
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const practiceRubixWebhook = webhook('practice-rubix', {
+  response: { mode: 'sync' },
+}).then(
+  http('handler', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, activation, connections } = ctx;
+
+    // Get configuration
+    const publicKey = activation.getVariable('fluentPublicKey');
+    const rawBody = activation.body || JSON.stringify(ctx.data);
+    const headers = activation.headers || {};
+
+    // Validate signature (Versori log can be passed directly)
+    const validator = new WebhookValidationService({ strictValidation: true }, log);
+    const result = await validator.validateWebhook(rawBody, headers, publicKey);
+
+    if (!result.isValid) {
+      return { status: 401, body: { error: result.error } };
+    }
+
+    // Parse payload
+    const payload = JSON.parse(rawBody);
+    const { entityRef, retailerId } = payload;
+
+    // Query Fluent
+    const client = await createClient({ ...ctx, log, connections });
+    await client.setRetailerId(retailerId);
+
+    const queryResult = await client.graphql({
+      query: `query($ref: String!) { order(ref: $ref) { id ref status } }`,
+      variables: { ref: entityRef }
+    });
+
+    const order = queryResult.data?.order;
+
+    return {
+      status: 200,
+      body: {
+        success: true,
+        order: { id: order.id, ref: order.ref, status: order.status }
+      }
+    };
+  })
+);
+```
+
+</details>
+
+---
+
+## Next Steps
+
+- Review [Module 3: Versori Integration](./webhook-validation-03-versori-integration.md) for more Versori patterns
+- Check [Rubix Webhook Template](../../../01-TEMPLATES/versori/workflows/rubix-webhooks/template-fluent-rubix-webhook-pattern.md) for production example
+- See [API Reference](./webhook-validation-07-api-reference.md) for complete method signatures
+
+---
+
+## Further Reading
+
+- [Fluent Commerce Webhook Documentation](https://docs.fluentcommerce.com/essential-knowledge/webhooks)
+- [Rubix Workflow HTTP Call Action](https://docs.fluentcommerce.com/rubix/workflows/http-call)
+- [Versori Platform Guide](../../../04-REFERENCE/platforms/versori/)