@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/01-TEMPLATES/versori/workflows/rubix-webhooks/template-webhook-rubix-order-attribute-update.md

@@ -1,824 +1,824 @@
----
-template_id: tpl-webhook-rubix-order-update
-canonical_filename: template-webhook-rubix-order-attribute-update.md
-sdk_version: ^0.1.39
-runtime: versori
-direction: webhook
-source: fluent-rubix-workflow
-destination: fluent-graphql
-entity: order
-format: json
-logging: versori
-status: stable
-features:
-  - webhook-validation
-  - fire-and-forget
-  - background-processing
-  - graphql-mutations
----
-
-# Template: Rubix Order Webhook → Attribute Update
-
-**SDK Version:** `^0.1.39` - `npm install @fluentcommerce/fc-connect-sdk@^0.1.39`
-**Last Updated:** 2025-01-25
-**Deployment Target:** Versori Platform
-
-**Production Ready:**
-- ✅ **Order-specific template** - Focused on attribute updates
-- ✅ **Production-ready modular structure** - Separate workflows, services, types
-- ✅ **GraphQL mutations** - Update order attributes
-- ✅ **Lightweight** - No SFTP/XML complexity
-- ✅ **Critical fixes applied** - retailerId validation
-- ✅ **Comprehensive documentation** - Testing, troubleshooting, monitoring
-
----
-
-## Overview
-
-Receive order webhooks from Rubix workflows and update order attributes via GraphQL mutations.
-
-**Pattern:**
-1. Validate webhook signature (~10-50ms)
-2. Return HTTP 200 OK immediately (fast acknowledgment)
-3. Background: Update order attributes via GraphQL mutation (~500ms)
-
-**Business Use Case:**
-- Rubix workflow sends webhook when order status changes
-- Handler updates custom attributes for tracking
-- Records processing timestamp
-- No external system integration needed
-
----
-
-## STEP 1: Understand This Template
-
-### What This Template Does
-
-**Core Functionality:**
-- Receives ORDER webhooks from Fluent Commerce Rubix workflows
-- Validates webhook signature for security
-- Returns fast HTTP 200 OK response (<100ms)
-- Background: Updates order attributes via GraphQL mutation
-
-**Key SDK Components:**
-- `WebhookValidationService` - Signature validation
-- `createClient()` - Universal client factory
-- `client.graphql()` - Execute mutations
-- Native Versori `log` - Structured logging
-
-**Critical Patterns:**
-- **Sync + Fire-and-Forget**: Fast validation, background processing
-- **Signature Validation**: Always validate webhook signatures
-- **RetailerId Validation**: Check before `setRetailerId()`
-- **GraphQL Mutations**: Update attributes, not create orders
-
-### When to Use This Template
-
-✅ **USE THIS TEMPLATE FOR:**
-- Order status change webhooks from Rubix workflows
-- Update custom order attributes for tracking
-- Record processing timestamps
-- Simple order updates without external systems
-
-❌ **DON'T USE FOR:**
-- Fulfilment webhooks (use fulfilment export template)
-- Complex exports to SFTP/S3 (use extraction templates)
-- Order creation (use GraphQL mutations directly)
-- High-volume order ingestion (use Batch API templates)
-
-### Business Use Cases
-
-**Use Case 1: Order Processing Timestamp Tracking**
-- Rubix workflow sends webhook when order moves to "PAID" status
-- Handler updates `webhookProcessedAt` attribute
-- Records processing timestamp
-- No external system integration needed
-
-**Use Case 2: Order Status Synchronization**
-- Rubix workflow sends webhook on status change
-- Handler updates custom attributes
-- Enables cross-system status reporting
-
----
-
-## STEP 2: Implementation Prompt for Claude Code
-
-**Copy this prompt and send to Claude Code to generate the complete implementation:**
-
-```
-Create a Versori webhook handler for Fluent Commerce Rubix ORDER events with signature validation and GraphQL attribute updates.
-
-REQUIREMENTS:
-1. Runtime: Versori Platform (HTTP webhook)
-2. Source: Rubix SendWebhook action (ORDER entity type only)
-3. Destination: Fluent Commerce GraphQL API (mutations)
-4. Format: JSON webhook payload
-5. Entity: ORDER
-
-KEY FEATURES:
-- Webhook signature validation using WebhookValidationService
-- Sync mode + fire-and-forget pattern for fast response
-- Background processing: GraphQL mutation for attribute updates
-- Modular architecture (workflows/, services/, types/)
-- Native Versori logging (no LoggingService)
-- Comprehensive error handling with SDK error types
-- RetailerId validation before setRetailerId()
-
-CRITICAL REQUIREMENTS:
-1. Webhook Mode: response: { mode: 'sync' }
-2. Signature Validation: WebhookValidationService with strictValidation: true
-3. RetailerId Validation: Check exists before client.setRetailerId()
-4. Background Processing: Fire-and-forget pattern (no await on background promise)
-5. GraphQL Mutation: Update order attributes only (not creation)
-6. Error Handling: Import and handle AuthenticationError, GraphQLError
-7. Type Safety: Use Logger, VersoriContext types (not any)
-
-SDK METHODS TO USE:
-- import { Buffer } from 'node:buffer' (for consistency)
-- createClient({ ...ctx, log })
-- await client.setRetailerId(retailerId) (with validation first!)
-- new WebhookValidationService({ strictValidation: true }, log)
-- await validator.validateWebhook(rawBody, headers, publicKey)
-- await client.graphql({ query, variables }) (mutation)
-
-FORBIDDEN PATTERNS:
-- ❌ LoggingService (use native log from context)
-- ❌ await on background processing (use fire-and-forget)
-- ❌ Missing retailerId validation before setRetailerId()
-- ❌ Using 'any' type (use Logger, VersoriContext from SDK)
-- ❌ Direct FluentClient instantiation (use createClient factory)
-- ❌ Generic error handling (use SDK error types)
-
-GRAPHQL MUTATION STRUCTURE:
-mutation UpdateOrderAttributes($input: UpdateOrderInput!) {
-  updateOrder(input: $input) {
-    id
-    ref
-    attributes {
-      name
-      type
-      value
-    }
-  }
-}
-
-GENERATE:
-1. package.json with dependencies
-2. index.ts (entry point - exports workflow)
-3. src/workflows/webhook/order-update-handler.ts (webhook entry)
-4. src/services/order-mutation.service.ts (GraphQL mutations)
-5. src/types/order.types.ts (TypeScript interfaces)
-6. readme.md with setup instructions
-
-Ensure all code is production-ready with proper error handling, signature validation, and type safety.
-```
-
----
-
-## STEP 3: Detailed Flow Documentation
-
-### Complete Processing Flow
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 1. RUBIX WEBHOOK RECEIVED                                   │
-│    POST https://{workspace}.versori.run/rubix-order         │
-│    Headers: fluent-signature                                │
-│    Body: { entityRef: "ORD-001", entityType: "ORDER" }      │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 2. SIGNATURE VALIDATION (Synchronous, ~10-50ms)             │
-│    - Extract rawBody and headers                            │
-│    - Get fluentPublicKey from activation                    │
-│    - WebhookValidationService.validateWebhook()             │
-│    - Return 400 if invalid                                  │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 3. PAYLOAD VALIDATION (Synchronous, ~5ms)                   │
-│    - Check entityRef exists                                 │
-│    - Check entityType === 'ORDER'                           │
-│    - Check retailerId exists                                │
-│    - Return 400 if missing required fields                  │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 4. HTTP 200 OK RESPONSE (Total: ~50ms)                      │
-│    - Return success immediately                             │
-│    - Background promise continues (fire-and-forget)         │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼ (Background - doesn't block response)
-┌─────────────────────────────────────────────────────────────┐
-│ 5. BACKGROUND PROCESSING (~300-500ms)                       │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5a. Initialize Fluent Client (~100ms)               │  │
-│    │     - createClient({ ...ctx, log })                 │  │
-│    │     - Validate retailerId exists                    │  │
-│    │     - client.setRetailerId(retailerId)              │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5b. Update Order Attributes (~200-400ms)            │  │
-│    │     - GraphQL mutation with attributes array        │  │
-│    │     - Handle GraphQLError if mutation fails         │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5c. Log Completion                                   │  │
-│    │     - Success: Log order ref and duration           │  │
-│    │     - Failure: Log error with category              │  │
-│    └─────────────────────────────────────────────────────┘  │
-└─────────────────────────────────────────────────────────────┘
-```
-
-### Response Timing
-
-| Stage | Timing | Blocking |
-|-------|--------|----------|
-| **Signature Validation** | ~10-50ms | ✅ Yes (blocks response) |
-| **Payload Validation** | ~5ms | ✅ Yes (blocks response) |
-| **HTTP 200 Response** | ~50-100ms | ✅ Fast acknowledgment |
-| **GraphQL Mutation** | ~200-400ms | ❌ No (background) |
-| **Total Background** | ~300-500ms | ❌ Fire-and-forget |
-
----
-
-## STEP 4: Production Modular Structure
-
-### Complete Project Structure
-
-```
-rubix-order-update/
-├── package.json                              # Dependencies and Versori config
-├── tsconfig.json                             # TypeScript configuration
-├── readme.md                                 # Setup and deployment instructions
-├── index.ts                                  # Entry point - exports workflow
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       └── order-update-handler.ts       # Webhook entry point
-    │
-    ├── services/
-    │   └── order-mutation.service.ts         # GraphQL mutations
-    │
-    └── types/
-        └── order.types.ts                    # TypeScript interfaces
-```
-
----
-
-## SDK Imports (Verified - Versori Optimized)
-
-```typescript
-// CRITICAL: Buffer import for consistency (even though not used for SFTP)
-import { Buffer } from 'node:buffer';
-
-// FC Connect SDK imports
-import {
-  createClient,
-  WebhookValidationService,
-  AuthenticationError,
-  GraphQLError,
-  type Logger,
-  type VersoriContext,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Versori platform imports
-import { webhook, http } from '@versori/run';
-import type { Context } from '@versori/run';
-```
-
----
-
-## Configuration
-
-### Activation Variables
-
-```json
-{
-  "fluentPublicKey": "-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----"
-}
-```
-
-### Connections
-
-| Connection | Description | Required |
-|------------|-------------|----------|
-| `fluent_commerce` | OAuth2 connection to Fluent Commerce | Yes |
-
----
-
-## Complete Working Code
-
-### 1. Entry Point (index.ts)
-
-```typescript
-/**
- * Entry point - Export webhook workflow for Versori platform
- */
-
-export { rubixOrderUpdateHandler } from './src/workflows/webhook/order-update-handler';
-```
-
-### 2. Webhook Handler (src/workflows/webhook/order-update-handler.ts)
-
-```typescript
-/**
- * Rubix Order Webhook Handler → Attribute Update
- *
- * Direction: Fluent Rubix Workflow (ORDER) → Versori → GraphQL Mutation
- */
-
-import { Buffer } from 'node:buffer';
-import { webhook } from '@versori/run';
-import type { Context } from '@versori/run';
-import {
-  WebhookValidationService,
-  type Logger,
-} from '@fluentcommerce/fc-connect-sdk';
-import { processOrderUpdate } from '../../services/order-mutation.service';
-
-export const rubixOrderUpdateHandler = webhook('rubix-order', {
-  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
-}, async (ctx: Context<any>) => {
-    const { log, activation } = ctx;
-
-    log.info('🚀 [WEBHOOK] Received Rubix order webhook', {
-      timestamp: new Date().toISOString(),
-      correlationId: activation?.id,
-    });
-
-    // ========================================
-  // STEP 1: VALIDATE SIGNATURE (Synchronous)
-    // ========================================
-
-    const publicKey = activation.getVariable('fluentPublicKey');
-    if (!publicKey) {
-      log.error('❌ [WEBHOOK] Missing fluentPublicKey configuration');
-      return {
-      status: 500,
-      body: {
-        success: false,
-        error: 'Missing fluentPublicKey configuration',
-        recommendation: 'Configure fluentPublicKey in activation variables',
-      },
-      };
-    }
-
-  // Extract raw body (Versori provides parsed data in ctx.data)
-    const rawBody = typeof ctx.data === 'string' ? ctx.data : JSON.stringify(ctx.data);
-
-  // Extract headers from request (ctx.request() is a function call)
-    const req = ctx.request?.() || {};
-    const headersObj = req.headers || {};
-  const headers = headersObj instanceof Headers
-    ? Object.fromEntries(headersObj.entries())
-    : headersObj;
-
-    log.info('🔍 [WEBHOOK] Validating webhook signature');
-
-    const validator = new WebhookValidationService({ strictValidation: true }, log as Logger);
-    const result = await validator.validateWebhook(rawBody, headers, publicKey);
-
-    if (!result.isValid) {
-      log.error('❌ [WEBHOOK] Invalid webhook signature', {
-        error: result.error,
-        algorithm: result.algorithm,
-      });
-      return {
-      status: 401,
-      body: {
-        success: false,
-        error: 'Invalid webhook signature',
-        recommendation: 'Verify fluentPublicKey matches Fluent environment',
-      },
-      };
-    }
-
-    log.info('✅ [WEBHOOK] Signature validated successfully', {
-      algorithm: result.algorithm,
-    });
-
-    // ========================================
-  // STEP 2: VALIDATE PAYLOAD (Synchronous)
-    // ========================================
-
-    const payload = typeof ctx.data === 'string' ? JSON.parse(ctx.data) : ctx.data;
-    const { entityRef, entityType, retailerId } = payload;
-
-    if (!entityRef) {
-      log.error('❌ [WEBHOOK] Missing entityRef in payload', { payload });
-      return {
-      status: 400,
-      body: {
-        success: false,
-        error: 'Missing entityRef in payload',
-        recommendation: 'Ensure Rubix SendWebhook includes order ref',
-      },
-      };
-    }
-
-    if (entityType !== 'ORDER') {
-      log.error('❌ [WEBHOOK] Invalid entity type', { entityType, expected: 'ORDER' });
-      return {
-      status: 400,
-      body: {
-        success: false,
-        error: `Invalid entity type: ${entityType}. Expected: ORDER`,
-        recommendation: 'Use fulfilment-export template for FULFILMENT webhooks',
-      },
-      };
-    }
-
-    if (!retailerId) {
-      log.error('❌ [WEBHOOK] Missing retailerId in payload', { payload });
-      return {
-      status: 400,
-      body: {
-        success: false,
-        error: 'Missing retailerId in payload',
-        recommendation: 'Ensure Rubix SendWebhook includes retailerId',
-      },
-      };
-    }
-
-  log.info('✅ [WEBHOOK] Validation passed, starting background processing', {
-      entityRef,
-      entityType,
-      retailerId,
-    });
-
-    // ========================================
-    // STEP 3: FIRE-AND-FORGET BACKGROUND PROCESSING
-    // ========================================
-
-  // ✅ Fire-and-forget: Start background processing WITHOUT await
-  // The promise continues execution after we return the response
-    processOrderUpdate(ctx, payload)
-      .then(() => {
-        log.info('✅ [BACKGROUND] Order updated successfully', {
-          orderRef: entityRef,
-        });
-      })
-      .catch((error: unknown) => {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        log.error('❌ [BACKGROUND] Order update failed', {
-          orderRef: entityRef,
-          error: errorMessage,
-          stack: error instanceof Error ? error.stack : undefined,
-          errorType: error instanceof Error ? error.constructor.name : typeof error,
-        });
-      });
-
-  // Return immediately (response sent with this return value)
-    return {
-    status: 200,
-    body: {
-      success: true,
-      entityType,
-      orderRef: entityRef,
-      message: 'Webhook validated and update started in background',
-      timestamp: new Date().toISOString(),
-      correlationId: activation?.id,
-    },
-    };
-});
-```
-
-### 3. Order Mutation Service (src/services/order-mutation.service.ts)
-
-```typescript
-/**
- * Order Mutation Service
- *
- * Handles GraphQL mutations for order attribute updates
- */
-
-import {
-  createClient,
-  AuthenticationError,
-  GraphQLError,
-  type Logger,
-  type VersoriContext,
-} from '@fluentcommerce/fc-connect-sdk';
-import type { RubixOrderPayload } from '../types/order.types';
-
-const UPDATE_ORDER_MUTATION = `
-  mutation UpdateOrderAttributes($input: UpdateOrderInput!) {
-    updateOrder(input: $input) {
-      id
-      ref
-      attributes {
-        name
-        type
-        value
-      }
-    }
-  }
-`;
-
-export async function processOrderUpdate(
-  ctx: VersoriContext,
-  payload: RubixOrderPayload
-): Promise<void> {
-  const log = ctx.log as Logger;
-  const { entityRef, retailerId } = payload;
-
-  const processingStartTime = Date.now();
-
-  log.info('🔄 [BACKGROUND] Starting order attribute update', {
-    timestamp: new Date().toISOString(),
-    orderRef: entityRef,
-  });
-
-  try {
-    // ========================================
-    // STEP 1: VALIDATE RETAILER ID
-    // ========================================
-
-    if (!retailerId) {
-      log.error('❌ [BACKGROUND] Missing retailerId in payload', {
-        orderRef: entityRef,
-      });
-      throw new Error('retailerId is required for GraphQL operations');
-    }
-
-    // ========================================
-    // STEP 2: INITIALIZE FLUENT CLIENT
-    // ========================================
-
-    const client = await createClient({ ...ctx, log });
-    await client.setRetailerId(retailerId);
-
-    // ========================================
-    // STEP 3: UPDATE ORDER ATTRIBUTES
-    // ========================================
-
-    log.info('📝 [BACKGROUND] Updating order attributes', { orderRef: entityRef });
-
-    await client.graphql({
-      query: UPDATE_ORDER_MUTATION,
-      variables: {
-        input: {
-          ref: entityRef,
-          attributes: [
-            {
-              name: 'webhookProcessedAt',
-              type: 'STRING',
-              value: new Date().toISOString(),
-            },
-            {
-              name: 'webhookSource',
-              type: 'STRING',
-              value: 'rubix-workflow',
-            },
-          ],
-        },
-      },
-    });
-
-    const duration = Date.now() - processingStartTime;
-    log.info('✅ [BACKGROUND] Order attributes updated successfully', {
-      orderRef: entityRef,
-      duration: `${duration}ms`,
-    });
-  } catch (error: unknown) {
-    let errorMessage = 'Unknown error';
-    let recommendation: string | undefined;
-    let errorCategory = 'UNKNOWN';
-
-    if (error instanceof GraphQLError) {
-      errorMessage = error.message;
-      recommendation = 'Review GraphQL mutation syntax and field permissions';
-      errorCategory = 'GRAPHQL';
-    } else if (error instanceof AuthenticationError) {
-      errorMessage = error.message;
-      recommendation = 'Verify Fluent Commerce credentials and retailerId';
-      errorCategory = 'AUTHENTICATION';
-    } else if (error instanceof Error) {
-      errorMessage = error.message;
-    } else {
-      errorMessage = String(error);
-    }
-
-    log.error('❌ [BACKGROUND] Order update failed', {
-      orderRef: entityRef,
-      error: errorMessage,
-      errorCategory,
-      recommendation,
-      stack: error instanceof Error ? error.stack : undefined,
-      errorType: error instanceof Error ? error.constructor.name : typeof error,
-    });
-
-    throw error;
-  }
-}
-```
-
-### 4. Type Definitions (src/types/order.types.ts)
-
-```typescript
-/**
- * Type definitions for Rubix order webhooks
- */
-
-export interface RubixOrderPayload {
-  id: string;
-  name: string;
-  accountId: string;
-  retailerId: string;
-  entityRef: string;
-  entityType: 'ORDER';
-  entityStatus?: string;
-  type: 'NORMAL' | string;
-  rootEntityId?: string;
-  rootEntityType?: string;
-  rootEntityRef?: string;
-  attributes?: Record<string, any>;
-  context?: Record<string, any>;
-}
-```
-
-### 5. Package Configuration (package.json)
-
-```json
-{
-  "name": "rubix-order-update",
-  "version": "2.0.0",
-  "description": "Rubix order webhook handler with attribute updates",
-  "type": "module",
-  "main": "index.ts",
-  "scripts": {
-    "dev": "versori dev",
-    "build": "versori build",
-    "deploy": "versori deploy",
-    "test": "jest",
-    "lint": "eslint src/**/*.ts"
-  },
-  "dependencies": {
-    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
-    "@versori/run": "latest"
-  },
-  "devDependencies": {
-    "@types/node": "^20.0.0",
-    "typescript": "^5.0.0",
-    "jest": "^29.0.0",
-    "@types/jest": "^29.0.0",
-    "eslint": "^8.0.0"
-  }
-}
-```
-
----
-
-## Key Patterns Explained
-
-### Pattern 1: RetailerId Validation Before setRetailerId()
-
-```typescript
-// ✅ CORRECT - Validate before use
-const retailerId = payload.retailerId;
-if (!retailerId) {
-  log.error('❌ [BACKGROUND] Missing retailerId in payload');
-  throw new Error('retailerId is required for GraphQL operations');
-}
-
-const client = await createClient({ ...ctx, log });
-await client.setRetailerId(retailerId);
-```
-
-**Why:** Missing retailerId causes 401 authentication errors with unclear messages.
-
-### Pattern 2: SDK Error Type Handling
-
-```typescript
-// ✅ CORRECT - Handle SDK error types
-catch (error: unknown) {
-  if (error instanceof GraphQLError) {
-    errorCategory = 'GRAPHQL';
-    recommendation = 'Review mutation syntax';
-  } else if (error instanceof AuthenticationError) {
-    errorCategory = 'AUTHENTICATION';
-    recommendation = 'Verify credentials';
-  }
-}
-```
-
-**Why:** SDK errors include recommendations for resolution.
-
----
-
-## Testing
-
-### 1. Unit Tests
-
-```typescript
-// src/services/__tests__/order-mutation.test.ts
-import { processOrderUpdate } from '../order-mutation.service';
-
-describe('Order Mutation Service', () => {
-  test('should update order successfully', async () => {
-    const mockCtx = {
-      log: { info: jest.fn(), error: jest.fn() },
-      activation: { getVariable: jest.fn() },
-    };
-
-    const payload = {
-      entityRef: 'ORD-001',
-      entityType: 'ORDER',
-      retailerId: '1',
-    };
-
-    await expect(processOrderUpdate(mockCtx, payload)).resolves.not.toThrow();
-  });
-});
-```
-
-### 2. Integration Test
-
-```bash
-# Test webhook with valid signature
-curl -X POST https://workspace.versori.run/rubix-order \
-  -H "Content-Type: application/json" \
-  -H "fluent-signature: <valid-signature>" \
-  -d '{
-    "entityType": "ORDER",
-    "entityRef": "ORD-001",
-    "retailerId": "1"
-  }'
-
-# Expected: 200 OK with { success: true, message: "..." }
-```
-
----
-
-## Production Checklist
-
-- [ ] Configure `fluentPublicKey` activation variable
-- [ ] Configure Fluent Commerce connection in Versori
-- [ ] Create Rubix workflow with SendWebhook action (ORDER events)
-- [ ] Build Event payload with entityRef, entityType, retailerId
-- [ ] Test webhook signature validation
-- [ ] Test GraphQL mutation with real order ref
-- [ ] Test error scenarios (invalid signature, missing retailerId)
-- [ ] Monitor response times (<100ms for validation)
-- [ ] Set up alerts for webhook/mutation failures
-- [ ] Document custom attributes being set
-
----
-
-## Troubleshooting Guide
-
-| Issue | Cause | Solution |
-|-------|-------|----------|
-| "Invalid webhook signature" | Wrong public key | Verify fluentPublicKey matches Fluent environment |
-| "Missing retailerId" | Rubix payload incomplete | Add retailerId to Rubix Event payload builder |
-| "GraphQL mutation failed" | Invalid permissions | Verify user has UPDATE_ORDER permission |
-| "401 authentication error" | Missing retailerId | Ensure retailerId validation before setRetailerId() |
-
----
-
-## Monitoring & Alerting
-
-### Success Response
-
-```json
-{
-  "success": true,
-  "entityType": "ORDER",
-  "orderRef": "ORD-001",
-  "message": "Webhook validated and update started in background",
-  "timestamp": "2025-01-25T14:30:00.000Z",
-  "correlationId": "act_123",
-  "processingMode": "async"
-}
-```
-
-### Key Metrics
-
-```typescript
-const METRICS = {
-  signatureValidationMs: 45,
-  totalResponseTimeMs: 50,
-  graphqlMutationMs: 250,
-  totalBackgroundMs: 350,
-};
-```
-
----
-
-## Related Documentation
-
-- [Fulfilment Export Template](./template-webhook-rubix-fulfilment-to-sftp-xml.md) - For FULFILMENT webhooks
-- [Webhook Validation Guide](../../../../02-CORE-GUIDES/webhook-validation/)
-- [Versori Platform Guide](../../../../04-REFERENCE/platforms/versori/)
-
----
-
-**Pattern**: Order webhook → GraphQL mutation → Attribute update
-**✅ Production-Ready**: Lightweight template with all critical fixes applied
-**Key Learning**: Always validate retailerId, handle SDK errors, fire-and-forget pattern
-**Critical**: RetailerId validation, proper error categorization, fast response
+---
+template_id: tpl-webhook-rubix-order-update
+canonical_filename: template-webhook-rubix-order-attribute-update.md
+sdk_version: ^0.1.39
+runtime: versori
+direction: webhook
+source: fluent-rubix-workflow
+destination: fluent-graphql
+entity: order
+format: json
+logging: versori
+status: stable
+features:
+  - webhook-validation
+  - fire-and-forget
+  - background-processing
+  - graphql-mutations
+---
+
+# Template: Rubix Order Webhook → Attribute Update
+
+**SDK Version:** `^0.1.39` - `npm install @fluentcommerce/fc-connect-sdk@^0.1.39`
+**Last Updated:** 2025-01-25
+**Deployment Target:** Versori Platform
+
+**Production Ready:**
+- ✅ **Order-specific template** - Focused on attribute updates
+- ✅ **Production-ready modular structure** - Separate workflows, services, types
+- ✅ **GraphQL mutations** - Update order attributes
+- ✅ **Lightweight** - No SFTP/XML complexity
+- ✅ **Critical fixes applied** - retailerId validation
+- ✅ **Comprehensive documentation** - Testing, troubleshooting, monitoring
+
+---
+
+## Overview
+
+Receive order webhooks from Rubix workflows and update order attributes via GraphQL mutations.
+
+**Pattern:**
+1. Validate webhook signature (~10-50ms)
+2. Return HTTP 200 OK immediately (fast acknowledgment)
+3. Background: Update order attributes via GraphQL mutation (~500ms)
+
+**Business Use Case:**
+- Rubix workflow sends webhook when order status changes
+- Handler updates custom attributes for tracking
+- Records processing timestamp
+- No external system integration needed
+
+---
+
+## STEP 1: Understand This Template
+
+### What This Template Does
+
+**Core Functionality:**
+- Receives ORDER webhooks from Fluent Commerce Rubix workflows
+- Validates webhook signature for security
+- Returns fast HTTP 200 OK response (<100ms)
+- Background: Updates order attributes via GraphQL mutation
+
+**Key SDK Components:**
+- `WebhookValidationService` - Signature validation
+- `createClient()` - Universal client factory
+- `client.graphql()` - Execute mutations
+- Native Versori `log` - Structured logging
+
+**Critical Patterns:**
+- **Sync + Fire-and-Forget**: Fast validation, background processing
+- **Signature Validation**: Always validate webhook signatures
+- **RetailerId Validation**: Check before `setRetailerId()`
+- **GraphQL Mutations**: Update attributes, not create orders
+
+### When to Use This Template
+
+✅ **USE THIS TEMPLATE FOR:**
+- Order status change webhooks from Rubix workflows
+- Update custom order attributes for tracking
+- Record processing timestamps
+- Simple order updates without external systems
+
+❌ **DON'T USE FOR:**
+- Fulfilment webhooks (use fulfilment export template)
+- Complex exports to SFTP/S3 (use extraction templates)
+- Order creation (use GraphQL mutations directly)
+- High-volume order ingestion (use Batch API templates)
+
+### Business Use Cases
+
+**Use Case 1: Order Processing Timestamp Tracking**
+- Rubix workflow sends webhook when order moves to "PAID" status
+- Handler updates `webhookProcessedAt` attribute
+- Records processing timestamp
+- No external system integration needed
+
+**Use Case 2: Order Status Synchronization**
+- Rubix workflow sends webhook on status change
+- Handler updates custom attributes
+- Enables cross-system status reporting
+
+---
+
+## STEP 2: Implementation Prompt for Claude Code
+
+**Copy this prompt and send to Claude Code to generate the complete implementation:**
+
+```
+Create a Versori webhook handler for Fluent Commerce Rubix ORDER events with signature validation and GraphQL attribute updates.
+
+REQUIREMENTS:
+1. Runtime: Versori Platform (HTTP webhook)
+2. Source: Rubix SendWebhook action (ORDER entity type only)
+3. Destination: Fluent Commerce GraphQL API (mutations)
+4. Format: JSON webhook payload
+5. Entity: ORDER
+
+KEY FEATURES:
+- Webhook signature validation using WebhookValidationService
+- Sync mode + fire-and-forget pattern for fast response
+- Background processing: GraphQL mutation for attribute updates
+- Modular architecture (workflows/, services/, types/)
+- Native Versori logging (no LoggingService)
+- Comprehensive error handling with SDK error types
+- RetailerId validation before setRetailerId()
+
+CRITICAL REQUIREMENTS:
+1. Webhook Mode: response: { mode: 'sync' }
+2. Signature Validation: WebhookValidationService with strictValidation: true
+3. RetailerId Validation: Check exists before client.setRetailerId()
+4. Background Processing: Fire-and-forget pattern (no await on background promise)
+5. GraphQL Mutation: Update order attributes only (not creation)
+6. Error Handling: Import and handle AuthenticationError, GraphQLError
+7. Type Safety: Use Logger, VersoriContext types (not any)
+
+SDK METHODS TO USE:
+- import { Buffer } from 'node:buffer' (for consistency)
+- createClient({ ...ctx, log })
+- await client.setRetailerId(retailerId) (with validation first!)
+- new WebhookValidationService({ strictValidation: true }, log)
+- await validator.validateWebhook(rawBody, headers, publicKey)
+- await client.graphql({ query, variables }) (mutation)
+
+FORBIDDEN PATTERNS:
+- ❌ LoggingService (use native log from context)
+- ❌ await on background processing (use fire-and-forget)
+- ❌ Missing retailerId validation before setRetailerId()
+- ❌ Using 'any' type (use Logger, VersoriContext from SDK)
+- ❌ Direct FluentClient instantiation (use createClient factory)
+- ❌ Generic error handling (use SDK error types)
+
+GRAPHQL MUTATION STRUCTURE:
+mutation UpdateOrderAttributes($input: UpdateOrderInput!) {
+  updateOrder(input: $input) {
+    id
+    ref
+    attributes {
+      name
+      type
+      value
+    }
+  }
+}
+
+GENERATE:
+1. package.json with dependencies
+2. index.ts (entry point - exports workflow)
+3. src/workflows/webhook/order-update-handler.ts (webhook entry)
+4. src/services/order-mutation.service.ts (GraphQL mutations)
+5. src/types/order.types.ts (TypeScript interfaces)
+6. readme.md with setup instructions
+
+Ensure all code is production-ready with proper error handling, signature validation, and type safety.
+```
+
+---
+
+## STEP 3: Detailed Flow Documentation
+
+### Complete Processing Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. RUBIX WEBHOOK RECEIVED                                   │
+│    POST https://{workspace}.versori.run/rubix-order         │
+│    Headers: fluent-signature                                │
+│    Body: { entityRef: "ORD-001", entityType: "ORDER" }      │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 2. SIGNATURE VALIDATION (Synchronous, ~10-50ms)             │
+│    - Extract rawBody and headers                            │
+│    - Get fluentPublicKey from activation                    │
+│    - WebhookValidationService.validateWebhook()             │
+│    - Return 400 if invalid                                  │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 3. PAYLOAD VALIDATION (Synchronous, ~5ms)                   │
+│    - Check entityRef exists                                 │
+│    - Check entityType === 'ORDER'                           │
+│    - Check retailerId exists                                │
+│    - Return 400 if missing required fields                  │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 4. HTTP 200 OK RESPONSE (Total: ~50ms)                      │
+│    - Return success immediately                             │
+│    - Background promise continues (fire-and-forget)         │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼ (Background - doesn't block response)
+┌─────────────────────────────────────────────────────────────┐
+│ 5. BACKGROUND PROCESSING (~300-500ms)                       │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5a. Initialize Fluent Client (~100ms)               │  │
+│    │     - createClient({ ...ctx, log })                 │  │
+│    │     - Validate retailerId exists                    │  │
+│    │     - client.setRetailerId(retailerId)              │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5b. Update Order Attributes (~200-400ms)            │  │
+│    │     - GraphQL mutation with attributes array        │  │
+│    │     - Handle GraphQLError if mutation fails         │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5c. Log Completion                                   │  │
+│    │     - Success: Log order ref and duration           │  │
+│    │     - Failure: Log error with category              │  │
+│    └─────────────────────────────────────────────────────┘  │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Response Timing
+
+| Stage | Timing | Blocking |
+|-------|--------|----------|
+| **Signature Validation** | ~10-50ms | ✅ Yes (blocks response) |
+| **Payload Validation** | ~5ms | ✅ Yes (blocks response) |
+| **HTTP 200 Response** | ~50-100ms | ✅ Fast acknowledgment |
+| **GraphQL Mutation** | ~200-400ms | ❌ No (background) |
+| **Total Background** | ~300-500ms | ❌ Fire-and-forget |
+
+---
+
+## STEP 4: Production Modular Structure
+
+### Complete Project Structure
+
+```
+rubix-order-update/
+├── package.json                              # Dependencies and Versori config
+├── tsconfig.json                             # TypeScript configuration
+├── readme.md                                 # Setup and deployment instructions
+├── index.ts                                  # Entry point - exports workflow
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       └── order-update-handler.ts       # Webhook entry point
+    │
+    ├── services/
+    │   └── order-mutation.service.ts         # GraphQL mutations
+    │
+    └── types/
+        └── order.types.ts                    # TypeScript interfaces
+```
+
+---
+
+## SDK Imports (Verified - Versori Optimized)
+
+```typescript
+// CRITICAL: Buffer import for consistency (even though not used for SFTP)
+import { Buffer } from 'node:buffer';
+
+// FC Connect SDK imports
+import {
+  createClient,
+  WebhookValidationService,
+  AuthenticationError,
+  GraphQLError,
+  type Logger,
+  type VersoriContext,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Versori platform imports
+import { webhook, http } from '@versori/run';
+import type { Context } from '@versori/run';
+```
+
+---
+
+## Configuration
+
+### Activation Variables
+
+```json
+{
+  "fluentPublicKey": "-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----"
+}
+```
+
+### Connections
+
+| Connection | Description | Required |
+|------------|-------------|----------|
+| `fluent_commerce` | OAuth2 connection to Fluent Commerce | Yes |
+
+---
+
+## Complete Working Code
+
+### 1. Entry Point (index.ts)
+
+```typescript
+/**
+ * Entry point - Export webhook workflow for Versori platform
+ */
+
+export { rubixOrderUpdateHandler } from './src/workflows/webhook/order-update-handler';
+```
+
+### 2. Webhook Handler (src/workflows/webhook/order-update-handler.ts)
+
+```typescript
+/**
+ * Rubix Order Webhook Handler → Attribute Update
+ *
+ * Direction: Fluent Rubix Workflow (ORDER) → Versori → GraphQL Mutation
+ */
+
+import { Buffer } from 'node:buffer';
+import { webhook } from '@versori/run';
+import type { Context } from '@versori/run';
+import {
+  WebhookValidationService,
+  type Logger,
+} from '@fluentcommerce/fc-connect-sdk';
+import { processOrderUpdate } from '../../services/order-mutation.service';
+
+export const rubixOrderUpdateHandler = webhook('rubix-order', {
+  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
+}, async (ctx: Context<any>) => {
+    const { log, activation } = ctx;
+
+    log.info('🚀 [WEBHOOK] Received Rubix order webhook', {
+      timestamp: new Date().toISOString(),
+      correlationId: activation?.id,
+    });
+
+    // ========================================
+  // STEP 1: VALIDATE SIGNATURE (Synchronous)
+    // ========================================
+
+    const publicKey = activation.getVariable('fluentPublicKey');
+    if (!publicKey) {
+      log.error('❌ [WEBHOOK] Missing fluentPublicKey configuration');
+      return {
+      status: 500,
+      body: {
+        success: false,
+        error: 'Missing fluentPublicKey configuration',
+        recommendation: 'Configure fluentPublicKey in activation variables',
+      },
+      };
+    }
+
+  // Extract raw body (Versori provides parsed data in ctx.data)
+    const rawBody = typeof ctx.data === 'string' ? ctx.data : JSON.stringify(ctx.data);
+
+  // Extract headers from request (ctx.request() is a function call)
+    const req = ctx.request?.() || {};
+    const headersObj = req.headers || {};
+  const headers = headersObj instanceof Headers
+    ? Object.fromEntries(headersObj.entries())
+    : headersObj;
+
+    log.info('🔍 [WEBHOOK] Validating webhook signature');
+
+    const validator = new WebhookValidationService({ strictValidation: true }, log as Logger);
+    const result = await validator.validateWebhook(rawBody, headers, publicKey);
+
+    if (!result.isValid) {
+      log.error('❌ [WEBHOOK] Invalid webhook signature', {
+        error: result.error,
+        algorithm: result.algorithm,
+      });
+      return {
+      status: 401,
+      body: {
+        success: false,
+        error: 'Invalid webhook signature',
+        recommendation: 'Verify fluentPublicKey matches Fluent environment',
+      },
+      };
+    }
+
+    log.info('✅ [WEBHOOK] Signature validated successfully', {
+      algorithm: result.algorithm,
+    });
+
+    // ========================================
+  // STEP 2: VALIDATE PAYLOAD (Synchronous)
+    // ========================================
+
+    const payload = typeof ctx.data === 'string' ? JSON.parse(ctx.data) : ctx.data;
+    const { entityRef, entityType, retailerId } = payload;
+
+    if (!entityRef) {
+      log.error('❌ [WEBHOOK] Missing entityRef in payload', { payload });
+      return {
+      status: 400,
+      body: {
+        success: false,
+        error: 'Missing entityRef in payload',
+        recommendation: 'Ensure Rubix SendWebhook includes order ref',
+      },
+      };
+    }
+
+    if (entityType !== 'ORDER') {
+      log.error('❌ [WEBHOOK] Invalid entity type', { entityType, expected: 'ORDER' });
+      return {
+      status: 400,
+      body: {
+        success: false,
+        error: `Invalid entity type: ${entityType}. Expected: ORDER`,
+        recommendation: 'Use fulfilment-export template for FULFILMENT webhooks',
+      },
+      };
+    }
+
+    if (!retailerId) {
+      log.error('❌ [WEBHOOK] Missing retailerId in payload', { payload });
+      return {
+      status: 400,
+      body: {
+        success: false,
+        error: 'Missing retailerId in payload',
+        recommendation: 'Ensure Rubix SendWebhook includes retailerId',
+      },
+      };
+    }
+
+  log.info('✅ [WEBHOOK] Validation passed, starting background processing', {
+      entityRef,
+      entityType,
+      retailerId,
+    });
+
+    // ========================================
+    // STEP 3: FIRE-AND-FORGET BACKGROUND PROCESSING
+    // ========================================
+
+  // ✅ Fire-and-forget: Start background processing WITHOUT await
+  // The promise continues execution after we return the response
+    processOrderUpdate(ctx, payload)
+      .then(() => {
+        log.info('✅ [BACKGROUND] Order updated successfully', {
+          orderRef: entityRef,
+        });
+      })
+      .catch((error: unknown) => {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        log.error('❌ [BACKGROUND] Order update failed', {
+          orderRef: entityRef,
+          error: errorMessage,
+          stack: error instanceof Error ? error.stack : undefined,
+          errorType: error instanceof Error ? error.constructor.name : typeof error,
+        });
+      });
+
+  // Return immediately (response sent with this return value)
+    return {
+    status: 200,
+    body: {
+      success: true,
+      entityType,
+      orderRef: entityRef,
+      message: 'Webhook validated and update started in background',
+      timestamp: new Date().toISOString(),
+      correlationId: activation?.id,
+    },
+    };
+});
+```
+
+### 3. Order Mutation Service (src/services/order-mutation.service.ts)
+
+```typescript
+/**
+ * Order Mutation Service
+ *
+ * Handles GraphQL mutations for order attribute updates
+ */
+
+import {
+  createClient,
+  AuthenticationError,
+  GraphQLError,
+  type Logger,
+  type VersoriContext,
+} from '@fluentcommerce/fc-connect-sdk';
+import type { RubixOrderPayload } from '../types/order.types';
+
+const UPDATE_ORDER_MUTATION = `
+  mutation UpdateOrderAttributes($input: UpdateOrderInput!) {
+    updateOrder(input: $input) {
+      id
+      ref
+      attributes {
+        name
+        type
+        value
+      }
+    }
+  }
+`;
+
+export async function processOrderUpdate(
+  ctx: VersoriContext,
+  payload: RubixOrderPayload
+): Promise<void> {
+  const log = ctx.log as Logger;
+  const { entityRef, retailerId } = payload;
+
+  const processingStartTime = Date.now();
+
+  log.info('🔄 [BACKGROUND] Starting order attribute update', {
+    timestamp: new Date().toISOString(),
+    orderRef: entityRef,
+  });
+
+  try {
+    // ========================================
+    // STEP 1: VALIDATE RETAILER ID
+    // ========================================
+
+    if (!retailerId) {
+      log.error('❌ [BACKGROUND] Missing retailerId in payload', {
+        orderRef: entityRef,
+      });
+      throw new Error('retailerId is required for GraphQL operations');
+    }
+
+    // ========================================
+    // STEP 2: INITIALIZE FLUENT CLIENT
+    // ========================================
+
+    const client = await createClient({ ...ctx, log });
+    await client.setRetailerId(retailerId);
+
+    // ========================================
+    // STEP 3: UPDATE ORDER ATTRIBUTES
+    // ========================================
+
+    log.info('📝 [BACKGROUND] Updating order attributes', { orderRef: entityRef });
+
+    await client.graphql({
+      query: UPDATE_ORDER_MUTATION,
+      variables: {
+        input: {
+          ref: entityRef,
+          attributes: [
+            {
+              name: 'webhookProcessedAt',
+              type: 'STRING',
+              value: new Date().toISOString(),
+            },
+            {
+              name: 'webhookSource',
+              type: 'STRING',
+              value: 'rubix-workflow',
+            },
+          ],
+        },
+      },
+    });
+
+    const duration = Date.now() - processingStartTime;
+    log.info('✅ [BACKGROUND] Order attributes updated successfully', {
+      orderRef: entityRef,
+      duration: `${duration}ms`,
+    });
+  } catch (error: unknown) {
+    let errorMessage = 'Unknown error';
+    let recommendation: string | undefined;
+    let errorCategory = 'UNKNOWN';
+
+    if (error instanceof GraphQLError) {
+      errorMessage = error.message;
+      recommendation = 'Review GraphQL mutation syntax and field permissions';
+      errorCategory = 'GRAPHQL';
+    } else if (error instanceof AuthenticationError) {
+      errorMessage = error.message;
+      recommendation = 'Verify Fluent Commerce credentials and retailerId';
+      errorCategory = 'AUTHENTICATION';
+    } else if (error instanceof Error) {
+      errorMessage = error.message;
+    } else {
+      errorMessage = String(error);
+    }
+
+    log.error('❌ [BACKGROUND] Order update failed', {
+      orderRef: entityRef,
+      error: errorMessage,
+      errorCategory,
+      recommendation,
+      stack: error instanceof Error ? error.stack : undefined,
+      errorType: error instanceof Error ? error.constructor.name : typeof error,
+    });
+
+    throw error;
+  }
+}
+```
+
+### 4. Type Definitions (src/types/order.types.ts)
+
+```typescript
+/**
+ * Type definitions for Rubix order webhooks
+ */
+
+export interface RubixOrderPayload {
+  id: string;
+  name: string;
+  accountId: string;
+  retailerId: string;
+  entityRef: string;
+  entityType: 'ORDER';
+  entityStatus?: string;
+  type: 'NORMAL' | string;
+  rootEntityId?: string;
+  rootEntityType?: string;
+  rootEntityRef?: string;
+  attributes?: Record<string, any>;
+  context?: Record<string, any>;
+}
+```
+
+### 5. Package Configuration (package.json)
+
+```json
+{
+  "name": "rubix-order-update",
+  "version": "2.0.0",
+  "description": "Rubix order webhook handler with attribute updates",
+  "type": "module",
+  "main": "index.ts",
+  "scripts": {
+    "dev": "versori dev",
+    "build": "versori build",
+    "deploy": "versori deploy",
+    "test": "jest",
+    "lint": "eslint src/**/*.ts"
+  },
+  "dependencies": {
+    "@fluentcommerce/fc-connect-sdk": "^0.1.39",
+    "@versori/run": "latest"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.0.0",
+    "jest": "^29.0.0",
+    "@types/jest": "^29.0.0",
+    "eslint": "^8.0.0"
+  }
+}
+```
+
+---
+
+## Key Patterns Explained
+
+### Pattern 1: RetailerId Validation Before setRetailerId()
+
+```typescript
+// ✅ CORRECT - Validate before use
+const retailerId = payload.retailerId;
+if (!retailerId) {
+  log.error('❌ [BACKGROUND] Missing retailerId in payload');
+  throw new Error('retailerId is required for GraphQL operations');
+}
+
+const client = await createClient({ ...ctx, log });
+await client.setRetailerId(retailerId);
+```
+
+**Why:** Missing retailerId causes 401 authentication errors with unclear messages.
+
+### Pattern 2: SDK Error Type Handling
+
+```typescript
+// ✅ CORRECT - Handle SDK error types
+catch (error: unknown) {
+  if (error instanceof GraphQLError) {
+    errorCategory = 'GRAPHQL';
+    recommendation = 'Review mutation syntax';
+  } else if (error instanceof AuthenticationError) {
+    errorCategory = 'AUTHENTICATION';
+    recommendation = 'Verify credentials';
+  }
+}
+```
+
+**Why:** SDK errors include recommendations for resolution.
+
+---
+
+## Testing
+
+### 1. Unit Tests
+
+```typescript
+// src/services/__tests__/order-mutation.test.ts
+import { processOrderUpdate } from '../order-mutation.service';
+
+describe('Order Mutation Service', () => {
+  test('should update order successfully', async () => {
+    const mockCtx = {
+      log: { info: jest.fn(), error: jest.fn() },
+      activation: { getVariable: jest.fn() },
+    };
+
+    const payload = {
+      entityRef: 'ORD-001',
+      entityType: 'ORDER',
+      retailerId: '1',
+    };
+
+    await expect(processOrderUpdate(mockCtx, payload)).resolves.not.toThrow();
+  });
+});
+```
+
+### 2. Integration Test
+
+```bash
+# Test webhook with valid signature
+curl -X POST https://workspace.versori.run/rubix-order \
+  -H "Content-Type: application/json" \
+  -H "fluent-signature: <valid-signature>" \
+  -d '{
+    "entityType": "ORDER",
+    "entityRef": "ORD-001",
+    "retailerId": "1"
+  }'
+
+# Expected: 200 OK with { success: true, message: "..." }
+```
+
+---
+
+## Production Checklist
+
+- [ ] Configure `fluentPublicKey` activation variable
+- [ ] Configure Fluent Commerce connection in Versori
+- [ ] Create Rubix workflow with SendWebhook action (ORDER events)
+- [ ] Build Event payload with entityRef, entityType, retailerId
+- [ ] Test webhook signature validation
+- [ ] Test GraphQL mutation with real order ref
+- [ ] Test error scenarios (invalid signature, missing retailerId)
+- [ ] Monitor response times (<100ms for validation)
+- [ ] Set up alerts for webhook/mutation failures
+- [ ] Document custom attributes being set
+
+---
+
+## Troubleshooting Guide
+
+| Issue | Cause | Solution |
+|-------|-------|----------|
+| "Invalid webhook signature" | Wrong public key | Verify fluentPublicKey matches Fluent environment |
+| "Missing retailerId" | Rubix payload incomplete | Add retailerId to Rubix Event payload builder |
+| "GraphQL mutation failed" | Invalid permissions | Verify user has UPDATE_ORDER permission |
+| "401 authentication error" | Missing retailerId | Ensure retailerId validation before setRetailerId() |
+
+---
+
+## Monitoring & Alerting
+
+### Success Response
+
+```json
+{
+  "success": true,
+  "entityType": "ORDER",
+  "orderRef": "ORD-001",
+  "message": "Webhook validated and update started in background",
+  "timestamp": "2025-01-25T14:30:00.000Z",
+  "correlationId": "act_123",
+  "processingMode": "async"
+}
+```
+
+### Key Metrics
+
+```typescript
+const METRICS = {
+  signatureValidationMs: 45,
+  totalResponseTimeMs: 50,
+  graphqlMutationMs: 250,
+  totalBackgroundMs: 350,
+};
+```
+
+---
+
+## Related Documentation
+
+- [Fulfilment Export Template](./template-webhook-rubix-fulfilment-to-sftp-xml.md) - For FULFILMENT webhooks
+- [Webhook Validation Guide](../../../../02-CORE-GUIDES/webhook-validation/)
+- [Versori Platform Guide](../../../../04-REFERENCE/platforms/versori/)
+
+---
+
+**Pattern**: Order webhook → GraphQL mutation → Attribute update
+**✅ Production-Ready**: Lightweight template with all critical fixes applied
+**Key Learning**: Always validate retailerId, handle SDK errors, fire-and-forget pattern
+**Critical**: RetailerId validation, proper error categorization, fast response