@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/02-CORE-GUIDES/webhook-validation/modules/webhook-validation-09-rubix-event-vs-http-call.md

@@ -1,432 +1,432 @@
-# Module 9: Rubix Event Webhooks vs HTTP Call Webhooks
-
-**Level:** Intermediate
-**Estimated Time:** 15 minutes
-
-## Overview
-
-This module clarifies the **TWO types of webhooks** that can come from Fluent Commerce Rubix workflows and which validation method to use for each.
-
-**CRITICAL DISTINCTION**: Rubix workflows can send webhooks in two different ways, with different payload structures and validation requirements.
-
----
-
-## Two Types of Rubix Webhooks
-
-### 1. Fluent Commerce Event Webhooks
-
-**Trigger:** Rubix workflow event system (automatic event firing)
-
-**Payload Structure:** Standardized Fluent Commerce event format
-
-**Example:**
-```json
-{
-  "id": "2a43a5d2-0c8f-484d-a0cf-c5353d040997",
-  "name": "order_webhook_status",
-  "accountId": "SAGIRISH",
-  "retailerId": "2",
-  "entityId": "6469",
-  "entityRef": "HD_G_FROM_POSTMAN_WEBHOOK_TEST",
-  "entityType": "ORDER",
-  "entitySubtype": "HD",
-  "entityStatus": "RECEIVED",
-  "type": "NORMAL",
-  "attributes": { ... },
-  "meta": { ... }
-}
-```
-
-**Key Fields:**
-- ✓ `name` - Event name (e.g., "order_webhook_status")
-- ✓ `id` - Event ID (UUID)
-- ✓ `retailerId` - Retailer ID
-
-**Headers:**
-```
-fluent-signature: C5W1vJHfJm44pejcN4C/Pch+mb62s8SjgTsmLIHzTLWh0Ew4d5No...
-flex.signature: V1YNn0KexNIjmLzAdcum2jNi8CX2ar1HN/ZiCrta7A7vDIl/8FY4...
-content-type: application/json
-```
-
----
-
-### 2. Rubix HTTP Call Webhooks
-
-**Trigger:** Manual HTTP Call action in Rubix workflow
-
-**Payload Structure:** Custom (user-defined in Rubix)
-
-**Example:**
-```json
-{
-  "entityId": "order-123",
-  "entityRef": "ORD-001",
-  "entityType": "order",
-  "triggerSource": "ORDER_FULFILLMENT",
-  "retailerId": "1",
-  "timestamp": "2025-11-07T12:34:56.789Z"
-}
-```
-
-**Key Fields:**
-- ✗ NO `name` field
-- ✗ NO `id` field (usually has `entityId` instead)
-- ✓ `retailerId` (if you include it)
-
-**Headers:** Same as Event webhooks
-```
-fluent-signature: ...
-flex.signature: ...
-content-type: application/json
-```
-
----
-
-## Which Validation Method to Use?
-
-### Option 1: WebhookValidationService (Works for BOTH)
-
-```typescript
-import { WebhookValidationService } from '@fluentcommerce/fc-connect-sdk';
-
-// ✅ Works for Event webhooks
-// ✅ Works for HTTP Call webhooks
-// ✅ Recommended for flexibility
-// ✅ Versori log can be passed directly (no wrapper needed)
-
-const validator = new WebhookValidationService({ strictValidation: true }, log);
-
-const result = await validator.validateWebhook(
-  rawBodyString,  // Raw payload
-  headers,        // Headers
-  publicKey       // Public key
-);
-
-if (!result.isValid) {
-  return { status: 401, body: { error: 'Invalid signature' } };
-}
-
-// Parse payload AFTER validation
-const payload = JSON.parse(rawBodyString);
-```
-
-**Use when:**
-- Building flexible webhook handlers that accept both types
-- Using Rubix HTTP Call action with custom payloads
-- You want one consistent pattern for all webhooks
-
----
-
-### Option 2: FluentClient.validateWebhook() (Event Webhooks Only)
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// ✅ Works for Event webhooks (has name, id, retailerId)
-// ❌ FAILS for HTTP Call webhooks (missing required fields)
-
-const client = await createClient({ ...ctx, log, connections });
-
-const payload = JSON.parse(rawBodyString); // Parse first
-
-const isValid = await client.validateWebhook(
-  payload,      // FluentWebhookPayload object
-  signature,    // Signature string
-  rawBodyString // Raw payload string
-);
-
-if (!isValid) {
-  return { status: 401, body: { error: 'Invalid signature' } };
-}
-
-// Process validated payload
-```
-
-**Use when:**
-- You KNOW you're receiving Event webhooks only
-- Payload has `name`, `id`, and `retailerId` fields
-- You want additional field validation
-
----
-
-## Decision Matrix
-
-| Webhook Type | Has `name`, `id`, `retailerId`? | Use WebhookValidationService | Use FluentClient.validateWebhook |
-|--------------|--------------------------------|------------------------------|----------------------------------|
-| **Event Webhook** | ✓ Yes | ✅ Recommended | ✅ Acceptable |
-| **HTTP Call Webhook** | ✗ No | ✅ Required | ❌ Will fail |
-| **Mixed (Both Types)** | ⚠️ Varies | ✅ Use this | ❌ Won't work for all |
-
----
-
-## Real-World Example Analysis
-
-### Your Webhook Sample (Event Webhook)
-
-```json
-{
-  "id": "2a43a5d2-0c8f-484d-a0cf-c5353d040997",  // ✓ Has id
-  "name": "order_webhook_status",                 // ✓ Has name
-  "retailerId": "2",                              // ✓ Has retailerId
-  "entityId": "6469",
-  "entityRef": "HD_G_FROM_POSTMAN_WEBHOOK_TEST"
-}
-```
-
-**Analysis:**
-- This is a **Fluent Commerce Event webhook**
-- Has all required fields: `name`, `id`, `retailerId`
-- Can use EITHER validation method
-- Sent automatically by Rubix event system
-
-**Headers:**
-```
-fluent-signature: C5W1vJHfJm44pejcN4C/Pch+mb62s8SjgTsmLIHzTLWh0Ew4d5No...
-flex.signature: V1YNn0KexNIjmLzAdcum2jNi8CX2ar1HN/ZiCrta7A7vDIl/8FY4...
-```
-
-Both signatures present (as documented).
-
----
-
-## Implementation Examples
-
-### Pattern 1: WebhookValidationService (Flexible)
-
-```typescript
-import { webhook, http } from '@versori/run';
-import {
-  createClient,
-  WebhookValidationService,
-} from '@fluentcommerce/fc-connect-sdk';
-
-export const flexibleWebhook = webhook('flexible-webhook', {
-  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 with WebhookValidationService (works for both types)
-    // Versori log can be passed directly (no wrapper needed)
-    const validator = new WebhookValidationService({ strictValidation: true }, log);
-    const result = await validator.validateWebhook(rawBody, headers, publicKey);
-
-    if (!result.isValid) {
-      log.error('Invalid signature', { error: result.error });
-      return { status: 401, body: { error: result.error } };
-    }
-
-    log.info('✅ Signature validated', { algorithm: result.algorithm });
-
-    // Parse payload
-    const payload = JSON.parse(rawBody);
-
-    // Determine webhook type
-    if (payload.name && payload.id && payload.retailerId) {
-      log.info('Processing Event webhook', { eventName: payload.name });
-      // Handle Event webhook
-      return await processEventWebhook(payload, ctx);
-    } else if (payload.entityId || payload.entityRef) {
-      log.info('Processing HTTP Call webhook', { entityRef: payload.entityRef });
-      // Handle HTTP Call webhook
-      return await processHttpCallWebhook(payload, ctx);
-    } else {
-      log.error('Unknown webhook type', { payloadKeys: Object.keys(payload) });
-      return { status: 400, body: { error: 'Unknown webhook type' } };
-    }
-  })
-);
-
-async function processEventWebhook(payload: any, ctx: any) {
-  // Process Event webhook with standard fields
-  return { status: 200, body: { success: true, type: 'event' } };
-}
-
-async function processHttpCallWebhook(payload: any, ctx: any) {
-  // Process HTTP Call webhook with custom fields
-  return { status: 200, body: { success: true, type: 'http_call' } };
-}
-```
-
----
-
-### Pattern 2: FluentClient.validateWebhook() (Event Webhooks Only)
-
-```typescript
-import { webhook, http } from '@versori/run';
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-export const eventWebhook = webhook('event-webhook', {
-  response: { mode: 'sync' },
-}).then(
-  http('handler', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, activation, connections } = ctx;
-
-    // Get raw body
-    const rawBody = activation.body || JSON.stringify(ctx.data);
-    const headers = activation.headers || {};
-
-    // Parse payload first
-    const payload = JSON.parse(rawBody);
-
-    // Verify this is an Event webhook
-    if (!payload.name || !payload.id || !payload.retailerId) {
-      log.error('Not an Event webhook', { payloadKeys: Object.keys(payload) });
-      return { status: 400, body: { error: 'Expected Event webhook with name, id, retailerId' } };
-    }
-
-    // Get signature
-    const signature = headers['fluent-signature'] || headers['flex.signature'];
-
-    // Create Fluent client
-    const client = await createClient({ ...ctx, log, connections });
-
-    // Validate using FluentClient (Event webhooks only)
-    const isValid = await client.validateWebhook(payload, signature, rawBody);
-
-    if (!isValid) {
-      log.error('Invalid Event webhook signature');
-      return { status: 401, body: { error: 'Invalid signature' } };
-    }
-
-    log.info('✅ Event webhook validated', { eventName: payload.name });
-
-    // Process Event webhook
-    return { status: 200, body: { success: true, eventId: payload.id } };
-  })
-);
-```
-
----
-
-## How to Identify Webhook Type
-
-### Method 1: Check Payload Structure
-
-```typescript
-const payload = JSON.parse(rawBody);
-
-if (payload.name && payload.id && payload.retailerId) {
-  // This is an Event webhook
-  console.log('Type: Event webhook');
-  console.log('Event name:', payload.name);
-} else if (payload.entityId || payload.entityRef) {
-  // This is an HTTP Call webhook
-  console.log('Type: HTTP Call webhook');
-  console.log('Entity ref:', payload.entityRef);
-} else {
-  // Unknown type
-  console.warn('Unknown webhook type');
-}
-```
-
-### Method 2: Check Rubix Configuration
-
-**Event Webhooks:**
-- Configured in: Fluent Commerce dashboard → Events → Webhook subscriptions
-- Trigger: Automatic (when events fire)
-- Payload: Standard Fluent event format
-
-**HTTP Call Webhooks:**
-- Configured in: Rubix workflow → Add HTTP Call action
-- Trigger: Manual (you configure when to send)
-- Payload: Custom (you define the JSON structure)
-
----
-
-## Best Practices
-
-### 1. Use WebhookValidationService for New Implementations
-
-```typescript
-// ✅ RECOMMENDED - Works for all webhook types
-const validator = new WebhookValidationService({}, logger);
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-```
-
-**Why:**
-- Flexible (works for both types)
-- Consistent validation pattern
-- No payload structure assumptions
-
-### 2. Only Use FluentClient.validateWebhook() if You're Sure
-
-```typescript
-// ⚠️ USE ONLY IF you know it's an Event webhook
-if (payload.name && payload.id && payload.retailerId) {
-  const isValid = await client.validateWebhook(payload, sig, raw);
-}
-```
-
-**Why:**
-- Adds additional field validation
-- Won't work for HTTP Call webhooks
-
-### 3. Validate BEFORE Parsing
-
-```typescript
-// ✅ CORRECT
-const result = await validator.validateWebhook(rawBody, headers, publicKey);
-if (result.isValid) {
-  const payload = JSON.parse(rawBody);
-}
-
-// ❌ WRONG (except when using FluentClient.validateWebhook)
-const payload = JSON.parse(rawBody);
-const result = await validator.validateWebhook(JSON.stringify(payload), headers, publicKey);
-```
-
----
-
-## Summary
-
-| Aspect | Event Webhook | HTTP Call Webhook |
-|--------|--------------|-------------------|
-| **Trigger** | Automatic (Fluent events) | Manual (HTTP Call action) |
-| **Payload** | Standard (name, id, retailerId) | Custom (user-defined) |
-| **Validation Method** | Both methods work | WebhookValidationService only |
-| **Signature Headers** | Both (fluent-signature, flex.signature) | Both (fluent-signature, flex.signature) |
-| **Public Key** | Required (x509 base64) | Required (x509 base64) |
-| **Use Case** | Event-driven integrations | Custom workflow integrations |
-
----
-
-## Key Takeaways
-
-1. **Two Types of Rubix Webhooks:**
-   - Event webhooks (standardized payload)
-   - HTTP Call webhooks (custom payload)
-
-2. **WebhookValidationService:**
-   - ✅ Works for BOTH types
-   - ✅ Recommended for flexibility
-   - ✅ Consistent validation pattern
-
-3. **FluentClient.validateWebhook():**
-   - ✅ Works for Event webhooks only
-   - ❌ Fails for HTTP Call webhooks
-   - ⚠️ Use only if you know webhook type
-
-4. **Signature Validation:**
-   - Both types send both signatures (fluent-signature, flex.signature)
-   - Same public key used for both types
-   - SDK auto-detects algorithm (SHA512 → MD5)
-
-5. **Identification:**
-   - Check for `name`, `id`, `retailerId` fields
-   - Event webhooks have all three
-   - HTTP Call webhooks have custom structure
-
----
-
-## Related Documentation
-
-- [Module 2: Quick Start](./webhook-validation-02-quick-start.md) - Basic webhook validation
-- [Module 8: Rubix Webhooks](./webhook-validation-08-rubix-webhooks.md) - HTTP Call webhook patterns
-- [Rubix Webhook Template](../../../01-TEMPLATES/versori/workflows/rubix-webhooks/template-fluent-rubix-webhook-pattern.md) - Production example
+# Module 9: Rubix Event Webhooks vs HTTP Call Webhooks
+
+**Level:** Intermediate
+**Estimated Time:** 15 minutes
+
+## Overview
+
+This module clarifies the **TWO types of webhooks** that can come from Fluent Commerce Rubix workflows and which validation method to use for each.
+
+**CRITICAL DISTINCTION**: Rubix workflows can send webhooks in two different ways, with different payload structures and validation requirements.
+
+---
+
+## Two Types of Rubix Webhooks
+
+### 1. Fluent Commerce Event Webhooks
+
+**Trigger:** Rubix workflow event system (automatic event firing)
+
+**Payload Structure:** Standardized Fluent Commerce event format
+
+**Example:**
+```json
+{
+  "id": "2a43a5d2-0c8f-484d-a0cf-c5353d040997",
+  "name": "order_webhook_status",
+  "accountId": "SAGIRISH",
+  "retailerId": "2",
+  "entityId": "6469",
+  "entityRef": "HD_G_FROM_POSTMAN_WEBHOOK_TEST",
+  "entityType": "ORDER",
+  "entitySubtype": "HD",
+  "entityStatus": "RECEIVED",
+  "type": "NORMAL",
+  "attributes": { ... },
+  "meta": { ... }
+}
+```
+
+**Key Fields:**
+- ✓ `name` - Event name (e.g., "order_webhook_status")
+- ✓ `id` - Event ID (UUID)
+- ✓ `retailerId` - Retailer ID
+
+**Headers:**
+```
+fluent-signature: C5W1vJHfJm44pejcN4C/Pch+mb62s8SjgTsmLIHzTLWh0Ew4d5No...
+flex.signature: V1YNn0KexNIjmLzAdcum2jNi8CX2ar1HN/ZiCrta7A7vDIl/8FY4...
+content-type: application/json
+```
+
+---
+
+### 2. Rubix HTTP Call Webhooks
+
+**Trigger:** Manual HTTP Call action in Rubix workflow
+
+**Payload Structure:** Custom (user-defined in Rubix)
+
+**Example:**
+```json
+{
+  "entityId": "order-123",
+  "entityRef": "ORD-001",
+  "entityType": "order",
+  "triggerSource": "ORDER_FULFILLMENT",
+  "retailerId": "1",
+  "timestamp": "2025-11-07T12:34:56.789Z"
+}
+```
+
+**Key Fields:**
+- ✗ NO `name` field
+- ✗ NO `id` field (usually has `entityId` instead)
+- ✓ `retailerId` (if you include it)
+
+**Headers:** Same as Event webhooks
+```
+fluent-signature: ...
+flex.signature: ...
+content-type: application/json
+```
+
+---
+
+## Which Validation Method to Use?
+
+### Option 1: WebhookValidationService (Works for BOTH)
+
+```typescript
+import { WebhookValidationService } from '@fluentcommerce/fc-connect-sdk';
+
+// ✅ Works for Event webhooks
+// ✅ Works for HTTP Call webhooks
+// ✅ Recommended for flexibility
+// ✅ Versori log can be passed directly (no wrapper needed)
+
+const validator = new WebhookValidationService({ strictValidation: true }, log);
+
+const result = await validator.validateWebhook(
+  rawBodyString,  // Raw payload
+  headers,        // Headers
+  publicKey       // Public key
+);
+
+if (!result.isValid) {
+  return { status: 401, body: { error: 'Invalid signature' } };
+}
+
+// Parse payload AFTER validation
+const payload = JSON.parse(rawBodyString);
+```
+
+**Use when:**
+- Building flexible webhook handlers that accept both types
+- Using Rubix HTTP Call action with custom payloads
+- You want one consistent pattern for all webhooks
+
+---
+
+### Option 2: FluentClient.validateWebhook() (Event Webhooks Only)
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// ✅ Works for Event webhooks (has name, id, retailerId)
+// ❌ FAILS for HTTP Call webhooks (missing required fields)
+
+const client = await createClient({ ...ctx, log, connections });
+
+const payload = JSON.parse(rawBodyString); // Parse first
+
+const isValid = await client.validateWebhook(
+  payload,      // FluentWebhookPayload object
+  signature,    // Signature string
+  rawBodyString // Raw payload string
+);
+
+if (!isValid) {
+  return { status: 401, body: { error: 'Invalid signature' } };
+}
+
+// Process validated payload
+```
+
+**Use when:**
+- You KNOW you're receiving Event webhooks only
+- Payload has `name`, `id`, and `retailerId` fields
+- You want additional field validation
+
+---
+
+## Decision Matrix
+
+| Webhook Type | Has `name`, `id`, `retailerId`? | Use WebhookValidationService | Use FluentClient.validateWebhook |
+|--------------|--------------------------------|------------------------------|----------------------------------|
+| **Event Webhook** | ✓ Yes | ✅ Recommended | ✅ Acceptable |
+| **HTTP Call Webhook** | ✗ No | ✅ Required | ❌ Will fail |
+| **Mixed (Both Types)** | ⚠️ Varies | ✅ Use this | ❌ Won't work for all |
+
+---
+
+## Real-World Example Analysis
+
+### Your Webhook Sample (Event Webhook)
+
+```json
+{
+  "id": "2a43a5d2-0c8f-484d-a0cf-c5353d040997",  // ✓ Has id
+  "name": "order_webhook_status",                 // ✓ Has name
+  "retailerId": "2",                              // ✓ Has retailerId
+  "entityId": "6469",
+  "entityRef": "HD_G_FROM_POSTMAN_WEBHOOK_TEST"
+}
+```
+
+**Analysis:**
+- This is a **Fluent Commerce Event webhook**
+- Has all required fields: `name`, `id`, `retailerId`
+- Can use EITHER validation method
+- Sent automatically by Rubix event system
+
+**Headers:**
+```
+fluent-signature: C5W1vJHfJm44pejcN4C/Pch+mb62s8SjgTsmLIHzTLWh0Ew4d5No...
+flex.signature: V1YNn0KexNIjmLzAdcum2jNi8CX2ar1HN/ZiCrta7A7vDIl/8FY4...
+```
+
+Both signatures present (as documented).
+
+---
+
+## Implementation Examples
+
+### Pattern 1: WebhookValidationService (Flexible)
+
+```typescript
+import { webhook, http } from '@versori/run';
+import {
+  createClient,
+  WebhookValidationService,
+} from '@fluentcommerce/fc-connect-sdk';
+
+export const flexibleWebhook = webhook('flexible-webhook', {
+  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 with WebhookValidationService (works for both types)
+    // Versori log can be passed directly (no wrapper needed)
+    const validator = new WebhookValidationService({ strictValidation: true }, log);
+    const result = await validator.validateWebhook(rawBody, headers, publicKey);
+
+    if (!result.isValid) {
+      log.error('Invalid signature', { error: result.error });
+      return { status: 401, body: { error: result.error } };
+    }
+
+    log.info('✅ Signature validated', { algorithm: result.algorithm });
+
+    // Parse payload
+    const payload = JSON.parse(rawBody);
+
+    // Determine webhook type
+    if (payload.name && payload.id && payload.retailerId) {
+      log.info('Processing Event webhook', { eventName: payload.name });
+      // Handle Event webhook
+      return await processEventWebhook(payload, ctx);
+    } else if (payload.entityId || payload.entityRef) {
+      log.info('Processing HTTP Call webhook', { entityRef: payload.entityRef });
+      // Handle HTTP Call webhook
+      return await processHttpCallWebhook(payload, ctx);
+    } else {
+      log.error('Unknown webhook type', { payloadKeys: Object.keys(payload) });
+      return { status: 400, body: { error: 'Unknown webhook type' } };
+    }
+  })
+);
+
+async function processEventWebhook(payload: any, ctx: any) {
+  // Process Event webhook with standard fields
+  return { status: 200, body: { success: true, type: 'event' } };
+}
+
+async function processHttpCallWebhook(payload: any, ctx: any) {
+  // Process HTTP Call webhook with custom fields
+  return { status: 200, body: { success: true, type: 'http_call' } };
+}
+```
+
+---
+
+### Pattern 2: FluentClient.validateWebhook() (Event Webhooks Only)
+
+```typescript
+import { webhook, http } from '@versori/run';
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+export const eventWebhook = webhook('event-webhook', {
+  response: { mode: 'sync' },
+}).then(
+  http('handler', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, activation, connections } = ctx;
+
+    // Get raw body
+    const rawBody = activation.body || JSON.stringify(ctx.data);
+    const headers = activation.headers || {};
+
+    // Parse payload first
+    const payload = JSON.parse(rawBody);
+
+    // Verify this is an Event webhook
+    if (!payload.name || !payload.id || !payload.retailerId) {
+      log.error('Not an Event webhook', { payloadKeys: Object.keys(payload) });
+      return { status: 400, body: { error: 'Expected Event webhook with name, id, retailerId' } };
+    }
+
+    // Get signature
+    const signature = headers['fluent-signature'] || headers['flex.signature'];
+
+    // Create Fluent client
+    const client = await createClient({ ...ctx, log, connections });
+
+    // Validate using FluentClient (Event webhooks only)
+    const isValid = await client.validateWebhook(payload, signature, rawBody);
+
+    if (!isValid) {
+      log.error('Invalid Event webhook signature');
+      return { status: 401, body: { error: 'Invalid signature' } };
+    }
+
+    log.info('✅ Event webhook validated', { eventName: payload.name });
+
+    // Process Event webhook
+    return { status: 200, body: { success: true, eventId: payload.id } };
+  })
+);
+```
+
+---
+
+## How to Identify Webhook Type
+
+### Method 1: Check Payload Structure
+
+```typescript
+const payload = JSON.parse(rawBody);
+
+if (payload.name && payload.id && payload.retailerId) {
+  // This is an Event webhook
+  console.log('Type: Event webhook');
+  console.log('Event name:', payload.name);
+} else if (payload.entityId || payload.entityRef) {
+  // This is an HTTP Call webhook
+  console.log('Type: HTTP Call webhook');
+  console.log('Entity ref:', payload.entityRef);
+} else {
+  // Unknown type
+  console.warn('Unknown webhook type');
+}
+```
+
+### Method 2: Check Rubix Configuration
+
+**Event Webhooks:**
+- Configured in: Fluent Commerce dashboard → Events → Webhook subscriptions
+- Trigger: Automatic (when events fire)
+- Payload: Standard Fluent event format
+
+**HTTP Call Webhooks:**
+- Configured in: Rubix workflow → Add HTTP Call action
+- Trigger: Manual (you configure when to send)
+- Payload: Custom (you define the JSON structure)
+
+---
+
+## Best Practices
+
+### 1. Use WebhookValidationService for New Implementations
+
+```typescript
+// ✅ RECOMMENDED - Works for all webhook types
+const validator = new WebhookValidationService({}, logger);
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+```
+
+**Why:**
+- Flexible (works for both types)
+- Consistent validation pattern
+- No payload structure assumptions
+
+### 2. Only Use FluentClient.validateWebhook() if You're Sure
+
+```typescript
+// ⚠️ USE ONLY IF you know it's an Event webhook
+if (payload.name && payload.id && payload.retailerId) {
+  const isValid = await client.validateWebhook(payload, sig, raw);
+}
+```
+
+**Why:**
+- Adds additional field validation
+- Won't work for HTTP Call webhooks
+
+### 3. Validate BEFORE Parsing
+
+```typescript
+// ✅ CORRECT
+const result = await validator.validateWebhook(rawBody, headers, publicKey);
+if (result.isValid) {
+  const payload = JSON.parse(rawBody);
+}
+
+// ❌ WRONG (except when using FluentClient.validateWebhook)
+const payload = JSON.parse(rawBody);
+const result = await validator.validateWebhook(JSON.stringify(payload), headers, publicKey);
+```
+
+---
+
+## Summary
+
+| Aspect | Event Webhook | HTTP Call Webhook |
+|--------|--------------|-------------------|
+| **Trigger** | Automatic (Fluent events) | Manual (HTTP Call action) |
+| **Payload** | Standard (name, id, retailerId) | Custom (user-defined) |
+| **Validation Method** | Both methods work | WebhookValidationService only |
+| **Signature Headers** | Both (fluent-signature, flex.signature) | Both (fluent-signature, flex.signature) |
+| **Public Key** | Required (x509 base64) | Required (x509 base64) |
+| **Use Case** | Event-driven integrations | Custom workflow integrations |
+
+---
+
+## Key Takeaways
+
+1. **Two Types of Rubix Webhooks:**
+   - Event webhooks (standardized payload)
+   - HTTP Call webhooks (custom payload)
+
+2. **WebhookValidationService:**
+   - ✅ Works for BOTH types
+   - ✅ Recommended for flexibility
+   - ✅ Consistent validation pattern
+
+3. **FluentClient.validateWebhook():**
+   - ✅ Works for Event webhooks only
+   - ❌ Fails for HTTP Call webhooks
+   - ⚠️ Use only if you know webhook type
+
+4. **Signature Validation:**
+   - Both types send both signatures (fluent-signature, flex.signature)
+   - Same public key used for both types
+   - SDK auto-detects algorithm (SHA512 → MD5)
+
+5. **Identification:**
+   - Check for `name`, `id`, `retailerId` fields
+   - Event webhooks have all three
+   - HTTP Call webhooks have custom structure
+
+---
+
+## Related Documentation
+
+- [Module 2: Quick Start](./webhook-validation-02-quick-start.md) - Basic webhook validation
+- [Module 8: Rubix Webhooks](./webhook-validation-08-rubix-webhooks.md) - HTTP Call webhook patterns
+- [Rubix Webhook Template](../../../01-TEMPLATES/versori/workflows/rubix-webhooks/template-fluent-rubix-webhook-pattern.md) - Production example