@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/versori/workflows/rubix-webhooks/template-webhook-rubix-fulfilment-to-sftp-xml-inline.md

@@ -1,1418 +1,1418 @@
----
-template_id: tpl-webhook-rubix-fulfilment-export-inline
-canonical_filename: template-webhook-rubix-fulfilment-to-sftp-xml-inline.md
-version: 2.0.0
-sdk_version: ^0.1.39
-runtime: versori
-direction: webhook
-source: fluent-rubix-workflow
-destination: sftp-xml
-entity: fulfilment
-format: xml
-logging: versori
-status: stable
-pattern: inline-mapping
-features:
-  - webhook-validation
-  - fire-and-forget
-  - background-processing
-  - xml-export
-  - sftp-integration
-  - graphql-queries
-  - inline-mapping
----
-
-# Template: Rubix Fulfilment Webhook → SFTP XML Export (Inline Mapping Pattern)
-
-**Template Version:** 2.0.0
-**SDK Version:** `^0.1.39` - `npm install @fluentcommerce/fc-connect-sdk@^0.1.39`
-**Last Updated:** 2025-11-12
-**Deployment Target:** Versori Platform
-**Mapping Pattern:** 🔵 **INLINE MAPPING** (Simpler, faster, webhook-optimized)
-
-> **📖 Pattern Selection Guide:**
-> - **Use THIS template (Inline)** for: Simple webhooks, tightly-coupled 3PL schemas, fast debugging
-> - **Use UniversalMapper version** for: Reusable configs, multi-environment deployments, complex transformations
-> - **See also:** [template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md](./template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md)
-
-**🆕 Version 2.0.0 - Production Ready:**
-- ✅ **Fulfilment-specific template** - Focused on 3PL/WMS integration
-- ✅ **Production-ready modular structure** - Separate workflows, services, types
-- ✅ **GraphQL fulfilment queries** - Fetch fulfilment + line items + order details
-- ✅ **Automatic pagination** - Handles fulfilments with 100+ items (up to 1000)
-- ✅ **XML generation** - Safe XML with automatic escaping
-- ✅ **SFTP upload** - Connection pooling with proper dispose()
-- ✅ **Critical fixes applied** - retailerId validation, SFTP options parameter, pagination
-- ✅ **Comprehensive documentation** - Testing, troubleshooting, monitoring
-
----
-
-## Overview
-
-Receive fulfilment webhooks from Rubix workflows, query fulfilment details, generate XML, and upload to 3PL/WMS SFTP server.
-
-**Pattern:**
-1. Validate webhook signature (~10-50ms)
-2. Return HTTP 200 OK immediately (fast acknowledgment)
-3. Background: Query fulfilment details → Generate XML → Upload to SFTP (~2-5s)
-
-**Business Use Case:**
-- Rubix workflow sends webhook when fulfilment is created/updated
-- Handler queries fulfilment details (items, order, addresses)
-- Generates XML fulfillment notification for 3PL/WMS
-- Uploads to partner SFTP server for warehouse processing
-
----
-
-## STEP 1: Understand This Template
-
-### What This Template Does
-
-**Core Functionality:**
-- Receives FULFILMENT webhooks from Fluent Commerce Rubix workflows
-- Validates webhook signature for security
-- Returns fast HTTP 200 OK response (<100ms)
-- Background: Queries fulfilment via GraphQL → Transforms to XML → Uploads to SFTP
-
-**Key SDK Components:**
-- `WebhookValidationService` - Signature validation with RSA/HMAC support
-- `createClient()` - Universal client factory (auto-detects Versori context)
-- `client.graphql()` - Query fulfilment details with automatic pagination
-- `XMLBuilder` - Safe XML generation with automatic escaping
-- `SftpDataSource` - SFTP operations with connection pooling
-- `ctx.credentials().getAccessToken()` - Retrieve SFTP credentials from Versori connection vault
-- Native Versori `log` - Structured logging from context
-
-**Pagination Support:**
-- Automatically handles fulfilments with 100+ line items
-- Uses two-query pattern: fulfilment details + paginated items
-- SDK auto-pagination: `pagination: { maxPages: 10 }` supports up to 1000 items
-- Logs pagination usage for monitoring
-
-**Critical Patterns:**
-- **Sync + Fire-and-Forget**: Fast validation, background processing
-- **Signature Validation**: Always validate `fluent-signature` or `flex.signature` headers
-- **Background Promises**: Use `.then().catch()` for error handling
-- **SFTP Credentials**: Retrieve from Versori connection vault (not activation variables)
-- **SFTP Cleanup**: Always call `dispose()` in finally blocks
-- **RetailerId Validation**: Check before `setRetailerId()` to prevent 401 errors
-
-### When to Use This Template
-
-✅ **USE THIS TEMPLATE FOR:**
-- Fulfilment created/updated webhooks from Rubix workflows
-- Export fulfilment details to 3PL/WMS via SFTP
-- Need XML format for warehouse management systems
-- Require signature validation for security
-- Need fast webhook acknowledgment + async processing
-
-❌ **DON'T USE FOR:**
-- Order webhooks (use order attribute update template)
-- Inventory webhooks (use inventory templates)
-- CSV/JSON exports (use format-specific templates)
-- Synchronous processing required (use standard http workflow)
-
-### Business Use Cases
-
-**Use Case: 3PL Warehouse Fulfillment Notification**
-- Rubix workflow sends webhook when fulfilment moves to "ALLOCATED" status
-- Handler queries fulfilment details (items, quantities, order info)
-- Generates XML fulfillment order for warehouse system
-- Uploads to 3PL SFTP server for pick/pack/ship processing
-- 3PL system imports XML and creates warehouse tasks
-
----
-
-## 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 FULFILMENT events with signature validation, GraphQL queries, XML generation, and SFTP upload.
-
-REQUIREMENTS:
-1. Runtime: Versori Platform (HTTP webhook)
-2. Source: Rubix SendWebhook action (FULFILMENT entity type only)
-3. Destination: SFTP XML export to 3PL/WMS partner
-4. Format: XML with fulfilment details, line items, order info
-5. Entity: FULFILMENT
-
-KEY FEATURES:
-- Webhook signature validation using WebhookValidationService
-- Sync mode + fire-and-forget pattern for fast response
-- Background processing: GraphQL query → Inline XML mapping → XML generation → SFTP upload
-- **Automatic pagination** - Handles fulfilments with 100+ items (up to 1000 items)
-- Two-query pattern: Fulfilment details + paginated items query
-- **Inline XML mapping** - Manual object construction (simple, no config files)
-- **XMLBuilder** - Safe XML generation with automatic escaping
-- Modular architecture (workflows/, services/, types/)
-- Native Versori logging (no LoggingService)
-- SFTP cleanup with dispose() in finally blocks
-- 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 Queries: Two separate queries (fulfilment + items with pagination)
-6. Pagination: Use SDK automatic pagination with maxPages: 10, first: 100
-7. **Inline Mapping**: Manual object construction for XML structure (no external config)
-8. XML Generation: Use XMLBuilder with automatic escaping
-9. SFTP Upload: Include options parameter { overwrite: true, createDirectories: true }
-10. SFTP Cleanup: Always dispose() in finally block
-11. Error Handling: Import and handle DataSourceError, AuthenticationError, GraphQLError
-12. Type Safety: Use Logger, VersoriContext types (not any)
-
-SDK METHODS TO USE:
-- import { Buffer } from 'node:buffer' (CRITICAL for Versori/Deno)
-- 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, pagination: { maxPages: 10 } })
-- Manual object construction for XML structure (inline mapping)
-- new XMLBuilder({ prettyPrint: true, xmlDeclaration: true, encoding: 'UTF-8' })
-- xmlBuilder.build(xmlData, 'FulfilmentExport')
-- await ctx.credentials().getAccessToken('sftp_export_server') - Retrieve SFTP credentials from connection vault
-- Buffer.from(accessToken, 'base64').toString('utf-8') - Decode Basic Auth credentials
-- new SftpDataSource(config, log) - config includes connectionId: 'sftp_export_server'
-- await sftp.uploadFile(remotePath, buffer, { overwrite: true, createDirectories: true })
-- await sftp.dispose() (CRITICAL in finally block)
-
-FORBIDDEN PATTERNS:
-- ❌ LoggingService (use native log from context)
-- ❌ await on background processing (use fire-and-forget)
-- ❌ Missing dispose() for SFTP
-- ❌ Missing options parameter in uploadFile()
-- ❌ Missing retailerId validation before setRetailerId()
-- ❌ Storing SFTP credentials in activation variables (use Versori connection vault)
-- ❌ Using 'any' type (use Logger, VersoriContext from SDK)
-- ❌ Direct FluentClient instantiation (use createClient factory)
-- ❌ Generic error handling (use SDK error types)
-
-GRAPHQL QUERY STRUCTURE:
-
-**Single Query with Nested Items (Schema-Validated)**
-```graphql
-query GetFulfilment($id: ID!, $first: Int!, $after: String) {
-  fulfilment(id: $id) {
-    id
-    ref
-    status
-    deliveryType
-    order {
-      id
-      ref
-      customer { firstName, lastName, email }
-    }
-    toAddress {
-      name, street, street2, city, state, postcode, country
-    }
-    fromAddress {
-      name, street, street2, city, state, postcode, country
-    }
-    items(first: $first, after: $after) {
-      edges {
-        node {
-          id
-          ref
-          requestedQuantity
-          filledQuantity
-          rejectedQuantity
-          orderItem {
-            id
-            ref
-            productRef
-            product { name }
-          }
-        }
-        cursor
-      }
-      pageInfo {
-        hasNextPage
-      }
-    }
-    createdOn
-    updatedOn
-  }
-}
-```
-
-**Why Single Query?**
-- Items are nested under the fulfilment type in Fluent Commerce schema
-- Single query with `connectionPath: 'fulfilment.items'` for SDK pagination
-- SDK automatically handles pagination with `pagination: { maxPages: 10 }` config
-- More efficient than two separate queries (reduces GraphQL roundtrips)
-
-XML OUTPUT STRUCTURE:
-<FulfilmentExport>
-  <Fulfilment ref="FF-001" status="ALLOCATED">
-    <OrderRef>ORD-123</OrderRef>
-    <DeliveryType>STANDARD</DeliveryType>
-    <Customer>
-      <FirstName>John</FirstName>
-      <LastName>Smith</LastName>
-      <Email>john@example.com</Email>
-    </Customer>
-    <ToAddress>
-      <Name>John Smith</Name>
-      <Street>123 Main St</Street>
-      <Street2>Apt 4B</Street2>
-      <City>New York</City>
-      <State>NY</State>
-      <Postcode>10001</Postcode>
-      <Country>US</Country>
-    </ToAddress>
-    <FromAddress>
-      <Name>Warehouse</Name>
-      <Street>456 Warehouse St</Street>
-      <City>Chicago</City>
-      <State>IL</State>
-      <Postcode>60601</Postcode>
-      <Country>US</Country>
-    </FromAddress>
-    <Items>
-      <Item ref="FFI-001">
-        <ProductRef>SKU-001</ProductRef>
-        <ProductName>Widget</ProductName>
-        <RequestedQuantity>2</RequestedQuantity>
-        <FilledQuantity>2</FilledQuantity>
-        <RejectedQuantity>0</RejectedQuantity>
-      </Item>
-    </Items>
-    <CreatedOn>2025-01-25T10:00:00Z</CreatedOn>
-    <UpdatedOn>2025-01-25T11:00:00Z</UpdatedOn>
-  </Fulfilment>
-</FulfilmentExport>
-
-GENERATE:
-1. package.json with dependencies
-2. index.ts (entry point - exports workflow)
-3. src/workflows/webhook/fulfilment-export-handler.ts (webhook entry)
-4. src/services/fulfilment-query.service.ts (GraphQL queries)
-5. src/services/xml-export.service.ts (Inline XML mapping + XMLBuilder + SFTP upload)
-6. src/types/fulfilment.types.ts (TypeScript interfaces)
-7. readme.md with setup instructions
-
-Ensure all code is production-ready with proper error handling, signature validation, SFTP cleanup, inline XML mapping, and type safety.
-```
-
----
-
-## STEP 3: Detailed Flow Documentation
-
-### Complete Processing Flow
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│ 1. RUBIX WEBHOOK RECEIVED                                   │
-│    POST https://{workspace}.versori.run/rubix-fulfilment    │
-│    Headers: fluent-signature                                │
-│    Body: { entityRef: "FF-001", entityType: "FULFILMENT" }  │
-└────────────────────┬────────────────────────────────────────┘
-                     │
-                     ▼
-┌─────────────────────────────────────────────────────────────┐
-│ 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 === 'FULFILMENT'                      │
-│    - 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 (~2-5 seconds)                     │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5a. Initialize Fluent Client (~100ms)               │  │
-│    │     - createClient({ ...ctx, log })                 │  │
-│    │     - Validate retailerId exists                    │  │
-│    │     - client.setRetailerId(retailerId)              │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5b. Query Fulfilment Details (~500-1500ms)          │  │
-│    │     - GraphQL query with nested fields              │  │
-│    │     - Fulfilment + items + order + addresses        │  │
-│    │     - Handle GraphQLError if query fails            │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5c. Generate XML (~50ms)                            │  │
-│    │     - Inline XML structure construction            │  │
-│    │     - XMLBuilder handles escaping automatically     │  │
-│    │     - Create Buffer from XML string                 │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5d. Upload to SFTP (~500-2000ms)                    │  │
-│    │     - Initialize SftpDataSource                     │  │
-│    │     - Upload with options parameter                 │  │
-│    │     - Handle DataSourceError if upload fails        │  │
-│    │     - ALWAYS dispose() in finally block             │  │
-│    └─────────────────────────────────────────────────────┘  │
-│    ┌─────────────────────────────────────────────────────┐  │
-│    │ 5e. Log Completion                                   │  │
-│    │     - Success: Log fulfilment 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 Query** | ~500-1500ms | ❌ No (background) |
-| **XML Generation** | ~50ms | ❌ No (background) |
-| **SFTP Upload** | ~500-2000ms | ❌ No (background) |
-| **Total Background** | ~2000-5000ms | ❌ Fire-and-forget |
-
----
-
-## STEP 4: Production Modular Structure
-
-### Complete Project Structure
-
-```
-rubix-fulfilment-export/
-├── 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/
-    │       └── fulfilment-export-handler.ts  # Webhook entry point
-    │
-    ├── services/
-    │   ├── fulfilment-query.service.ts       # GraphQL queries
-    │   └── xml-export.service.ts             # Inline XML mapping + XMLBuilder + SFTP upload
-    │
-    └── types/
-        └── fulfilment.types.ts               # TypeScript interfaces
-```
-
-**Why This Structure?**
-- ✅ **Clear separation**: Webhook handlers vs business logic
-- ✅ **Reusable services**: Query and export logic can be unit tested
-- ✅ **Simple inline mapping**: XML structure defined directly in code (no config files)
-- ✅ **Type safety**: TypeScript interfaces for better IDE support
-- ✅ **Scalable**: Easy to add more fulfilment webhooks
-- ✅ **Testable**: Services can be mocked and tested independently
-- ✅ **Fast debugging**: XML structure visible directly in code
-
----
-
-## SDK Imports (Verified - Versori Optimized)
-
-```typescript
-// CRITICAL: Buffer import required for Versori/Deno runtime
-import { Buffer } from 'node:buffer';
-
-// FC Connect SDK imports
-import {
-  createClient,
-  WebhookValidationService,
-  XMLBuilder,
-  SftpDataSource,
-  DataSourceError,
-  AuthenticationError,
-  GraphQLError,
-  type Logger,
-  type VersoriContext,
-} from '@fluentcommerce/fc-connect-sdk';
-
-// Versori platform imports
-import { webhook } from '@versori/run';
-import type { Context } from '@versori/run';
-```
-
----
-
-## Configuration
-
-### Activation Variables
-
-```json
-{
-  "fluentPublicKey": "-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----",
-  "sftpHost": "sftp.3pl-partner.com",
-  "sftpPort": 22,
-  "sftpRemotePath": "/incoming/fulfilments/"
-}
-```
-
-> **Important:** `sftpUsername` and `sftpPassword` are **NOT** stored in activation variables. They are securely retrieved from the `sftp_export_server` connection vault at runtime. See the SFTP Credential Management section below for details.
-
-### Connections
-
-| Connection | Description | Required |
-|------------|-------------|----------|
-| `fluent_commerce` | OAuth2 connection to Fluent Commerce | Yes |
-| `sftp_export_server` | Basic Auth connection for SFTP credentials (username/password) | Yes |
-
-## SFTP Credential Management
-
-Fetch credentials securely from Versori connection vault using `ctx.credentials().getAccessToken()`:
-
-**Benefits:**
-- ✅ Credentials stored securely in Versori vault
-- ✅ Centralized management - update in one place
-- ✅ Access control enforced by platform
-- ✅ No credentials in activation variables
-- ✅ Explicit error handling with validation
-
-### Setup Steps
-
-1. In Versori Dashboard → Connections → Add Connection
-2. Name: `sftp_export_server`
-3. Type: Basic Auth
-4. Enter SFTP username and password
-5. Save connection
-6. Reference in code: `ctx.credentials().getAccessToken('sftp_export_server')`
-
----
-
-## Complete Working Code
-
-### 1. Entry Point (index.ts)
-
-```typescript
-/**
- * Entry point - Export webhook workflow for Versori platform
- */
-
-export { rubixFulfilmentExportHandler } from './src/workflows/webhook/fulfilment-export-handler';
-```
-
-### 2. Webhook Handler (src/workflows/webhook/fulfilment-export-handler.ts)
-
-```typescript
-/**
- * Rubix Fulfilment Webhook Handler → SFTP XML Export
- *
- * Direction: Fluent Rubix Workflow (FULFILMENT) → Versori → GraphQL → XML → SFTP
- */
-
-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 { processFulfilmentExport } from '../../services/fulfilment-query.service';
-
-export const rubixFulfilmentExportHandler = webhook('rubix-fulfilment', {
-  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
-}, async (ctx: Context<any>) => {
-  const { log, activation } = ctx;
-
-  log.info('🚀 [WEBHOOK] Received Rubix fulfilment 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 fulfilment ref',
-      },
-    };
-  }
-
-  if (entityType !== 'FULFILMENT') {
-    log.error('❌ [WEBHOOK] Invalid entity type', { entityType, expected: 'FULFILMENT' });
-    return {
-      status: 400,
-      body: {
-        success: false,
-        error: `Invalid entity type: ${entityType}. Expected: FULFILMENT`,
-        recommendation: 'Use order-attribute-update template for ORDER 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
-  processFulfilmentExport(ctx, payload)
-    .then(() => {
-      log.info('✅ [BACKGROUND] Fulfilment exported successfully', {
-        fulfilmentRef: entityRef,
-      });
-    })
-    .catch((error: unknown) => {
-      const errorMessage = error instanceof Error ? error.message : String(error);
-      log.error('❌ [BACKGROUND] Fulfilment export failed', {
-        fulfilmentRef: 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,
-      fulfilmentRef: entityRef,
-      message: 'Webhook validated and export started in background',
-      timestamp: new Date().toISOString(),
-      correlationId: activation?.id,
-    },
-  };
-});
-```
-
-### 3. Fulfilment Query Service (src/services/fulfilment-query.service.ts)
-
-```typescript
-/**
- * Fulfilment Query Service
- *
- * Handles GraphQL queries for fulfilment details and orchestrates XML export
- */
-
-import {
-  createClient,
-  DataSourceError,
-  AuthenticationError,
-  GraphQLError,
-  type Logger,
-  type VersoriContext,
-} from '@fluentcommerce/fc-connect-sdk';
-import { exportFulfilmentToSFTP } from './xml-export.service';
-import type { RubixFulfilmentPayload, FulfilmentData } from '../types/fulfilment.types';
-
-// Single query with nested items (schema-validated structure)
-const FULFILMENT_QUERY = `
-  query GetFulfilment($id: ID!, $first: Int!, $after: String) {
-    fulfilment(id: $id) {
-      id
-      ref
-      status
-      deliveryType
-      order {
-        id
-        ref
-        customer {
-          firstName
-          lastName
-          email
-        }
-      }
-      toAddress {
-        name
-        street
-        street2
-        city
-        state
-        postcode
-        country
-      }
-      fromAddress {
-        name
-        street
-        street2
-        city
-        state
-        postcode
-        country
-      }
-      items(first: $first, after: $after) {
-        edges {
-          node {
-            id
-            ref
-            requestedQuantity
-            filledQuantity
-            rejectedQuantity
-            orderItem {
-              id
-              ref
-              productRef
-              product {
-                name
-              }
-            }
-          }
-          cursor
-        }
-        pageInfo {
-          hasNextPage
-        }
-      }
-      createdOn
-      updatedOn
-    }
-  }
-`;
-
-export async function processFulfilmentExport(
-  ctx: VersoriContext,
-  payload: RubixFulfilmentPayload
-): Promise<void> {
-  const log = ctx.log as Logger;
-  const { entityRef, retailerId } = payload;
-
-  const processingStartTime = Date.now();
-
-  log.info('🔄 [BACKGROUND] Starting fulfilment export', {
-    timestamp: new Date().toISOString(),
-    fulfilmentRef: entityRef,
-  });
-
-  try {
-    // ========================================
-    // STEP 1: VALIDATE RETAILER ID
-    // ========================================
-
-    if (!retailerId) {
-      log.error('❌ [BACKGROUND] Missing retailerId in payload', {
-        fulfilmentRef: 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: QUERY FULFILMENT WITH NESTED ITEMS
-    // ========================================
-
-    log.info('🔍 [BACKGROUND] Querying fulfilment with items', { fulfilmentRef: entityRef });
-
-    const result = await client.graphql({
-      query: FULFILMENT_QUERY,
-      variables: {
-        id: entityRef,  // ✅ Use 'id' parameter (schema-validated)
-        first: 100,
-      },
-      pagination: {
-        connectionPath: 'fulfilment.items',  // ✅ Nested connection pagination
-        maxPages: 10, // Handles up to 1000 items (100 per page × 10 pages)
-      },
-    });
-
-    const fulfilmentData = result.data?.fulfilment as FulfilmentData | null;
-
-    if (!fulfilmentData) {
-      log.error('❌ [BACKGROUND] Fulfilment not found', { fulfilmentRef: entityRef });
-      throw new Error(`Fulfilment not found: ${entityRef}`);
-    }
-
-    const itemCount = fulfilmentData.items?.edges?.length || 0;
-
-    log.info('✅ [BACKGROUND] Fulfilment and items queried successfully', {
-      fulfilmentRef: fulfilmentData.ref,
-      status: fulfilmentData.status,
-      itemCount,
-      orderRef: fulfilmentData.order?.ref,
-      paginationUsed: result.metadata?.totalPages > 1,
-    });
-
-    // ========================================
-    // STEP 5: EXPORT TO SFTP
-    // ========================================
-
-    await exportFulfilmentToSFTP(ctx, completeFullfilmentData, log);
-
-    const duration = Date.now() - processingStartTime;
-    log.info('✅ [BACKGROUND] Fulfilment export completed', {
-      fulfilmentRef: 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 query 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 DataSourceError) {
-      errorMessage = error.message;
-      recommendation = 'Check SFTP configuration and connectivity';
-      errorCategory = 'DATA_SOURCE';
-    } else if (error instanceof Error) {
-      errorMessage = error.message;
-    } else {
-      errorMessage = String(error);
-    }
-
-    log.error('❌ [BACKGROUND] Fulfilment export failed', {
-      fulfilmentRef: entityRef,
-      error: errorMessage,
-      errorCategory,
-      recommendation,
-      stack: error instanceof Error ? error.stack : undefined,
-      errorType: error instanceof Error ? error.constructor.name : typeof error,
-    });
-
-    throw error;
-  }
-}
-```
-
-### 4. XML Export Service (src/services/xml-export.service.ts)
-
-```typescript
-/**
- * XML Export Service
- *
- * Handles XML generation and SFTP upload for fulfilment exports
- * Uses inline mapping (manual object construction) for XML structure
- */
-
-import { Buffer } from 'node:buffer';
-import {
-  XMLBuilder,
-  SftpDataSource,
-  type Logger,
-  type VersoriContext,
-} from '@fluentcommerce/fc-connect-sdk';
-import type { FulfilmentData } from '../types/fulfilment.types';
-
-export async function exportFulfilmentToSFTP(
-  ctx: VersoriContext,
-  fulfilmentData: FulfilmentData,
-  log: Logger
-): Promise<void> {
-  const { activation } = ctx;
-
-  log.info('📝 [BACKGROUND] Generating XML for fulfilment', {
-    fulfilmentRef: fulfilmentData.ref,
-  });
-
-  // ========================================
-  // STEP 1: BUILD XML STRUCTURE (INLINE MAPPING)
-  // ========================================
-
-  const xmlBuilder = new XMLBuilder({
-    prettyPrint: true,
-    xmlDeclaration: true,
-    encoding: 'UTF-8',
-  });
-
-  // Inline XML structure construction
-  const xmlData = {
-    Fulfilment: {
-      '@ref': fulfilmentData.ref,
-      '@status': fulfilmentData.status,
-      OrderRef: fulfilmentData.order?.ref || '',
-      DeliveryType: fulfilmentData.deliveryType || '',
-      Customer: fulfilmentData.order?.customer
-        ? {
-            FirstName: fulfilmentData.order.customer.firstName || '',
-            LastName: fulfilmentData.order.customer.lastName || '',
-            Email: fulfilmentData.order.customer.email || '',
-          }
-        : {},
-      ToAddress: fulfilmentData.toAddress
-        ? {
-            Name: fulfilmentData.toAddress.name || '',
-            Street: fulfilmentData.toAddress.street || '',
-            Street2: fulfilmentData.toAddress.street2 || '',
-            City: fulfilmentData.toAddress.city || '',
-            State: fulfilmentData.toAddress.state || '',
-            Postcode: fulfilmentData.toAddress.postcode || '',
-            Country: fulfilmentData.toAddress.country || '',
-          }
-        : {},
-      FromAddress: fulfilmentData.fromAddress
-        ? {
-            Name: fulfilmentData.fromAddress.name || '',
-            Street: fulfilmentData.fromAddress.street || '',
-            Street2: fulfilmentData.fromAddress.street2 || '',
-            City: fulfilmentData.fromAddress.city || '',
-            State: fulfilmentData.fromAddress.state || '',
-            Postcode: fulfilmentData.fromAddress.postcode || '',
-            Country: fulfilmentData.fromAddress.country || '',
-          }
-        : {},
-      Items: {
-        Item:
-          fulfilmentData.items?.edges?.map(edge => ({
-            '@ref': edge.node.ref,
-            ProductRef: edge.node.orderItem?.productRef || '',
-            ProductName: edge.node.orderItem?.product?.name || '',
-            RequestedQuantity: edge.node.requestedQuantity || 0,
-            FilledQuantity: edge.node.filledQuantity,
-            RejectedQuantity: edge.node.rejectedQuantity,
-          })) || [],
-      },
-      CreatedOn: fulfilmentData.createdOn,
-      UpdatedOn: fulfilmentData.updatedOn,
-    },
-  };
-
-  const xmlString = xmlBuilder.build(xmlData, 'FulfilmentExport');
-  const xmlBuffer = Buffer.from(xmlString, 'utf8');
-
-  log.info('✅ [BACKGROUND] XML generated successfully', {
-    fulfilmentRef: fulfilmentData.ref,
-    xmlSizeBytes: xmlBuffer.length,
-    xmlSizeKB: Math.round(xmlBuffer.length / 1024),
-  });
-
-  // ========================================
-  // STEP 2: UPLOAD TO SFTP
-  // ========================================
-
-  log.info('📤 [BACKGROUND] Preparing SFTP upload', {
-    fulfilmentRef: fulfilmentData.ref,
-  });
-
-  // ========================================
-  // SFTP CREDENTIAL RETRIEVAL
-  // ========================================
-
-  /**
-   * Retrieve SFTP credentials from connection configuration
-   * 
-   * Connection Name: 'sftp_export_server' (must match the connection name in Versori UI)
-   * Auth Type: Basic Authentication (username + password)
-   */
-  log.info('🔐 [BACKGROUND] Retrieving SFTP credentials from connection configuration');
-
-  let sftpUsername: string;
-  let sftpPassword: string;
-
-  try {
-    // Retrieve credentials from the 'sftp_export_server' connection
-    const sftpCred = await ctx.credentials().getAccessToken('sftp_export_server');
-
-    if (!sftpCred?.accessToken) {
-      throw new Error('No SFTP credentials found in connection configuration');
-    }
-
-    // Decode base64 accessToken to get "username:password"
-    const rawBasicAuth = Buffer.from(sftpCred.accessToken, 'base64').toString('utf-8');
-
-    // Split on ':' to extract username and password
-    const parts = rawBasicAuth.split(':');
-
-    if (parts.length !== 2) {
-      throw new Error('Invalid SFTP credential format - expected username:password');
-    }
-
-    sftpUsername = parts[0];
-    sftpPassword = parts[1];
-
-    log.info('✅ [BACKGROUND] SFTP credentials retrieved successfully', {
-      hasUsername: !!sftpUsername,
-      hasPassword: !!sftpPassword,
-      usernameLength: sftpUsername.length,
-      passwordLength: sftpPassword.length,
-    });
-  } catch (error: any) {
-    log.error('❌ [BACKGROUND] Failed to retrieve SFTP credentials', {
-      message: error instanceof Error ? error.message : String(error),
-      stack: error instanceof Error ? error.stack : undefined,
-      errorType: error instanceof Error ? error.constructor.name : 'Error',
-      recommendation: 'Please ensure the SFTP connection "sftp_export_server" is configured in the Connections section with Basic Authentication (username and password)',
-    });
-    throw new Error(
-      `Failed to retrieve SFTP credentials from connection configuration: ${error instanceof Error ? error.message : String(error)}. ` +
-      'Please ensure the SFTP connection is configured in the Connections section with Basic Authentication (username and password)'
-    );
-  }
-
-  // Get SFTP configuration from activation variables
-  const sftpHost = activation.getVariable('sftpHost');
-  const sftpPort = parseInt(activation.getVariable('sftpPort') || '22', 10);
-  const sftpRemotePath = activation.getVariable('sftpRemotePath') || '/incoming/fulfilments/';
-
-  if (!sftpHost) {
-    log.error('⚠️ [BACKGROUND] SFTP configuration missing', {
-      recommendation: 'Configure sftpHost activation variable',
-      fulfilmentRef: fulfilmentData.ref,
-    });
-    throw new Error('SFTP configuration missing: sftpHost is required');
-  }
-
-  const sftpConfig = {
-    type: 'SFTP_XML' as const,
-    connectionId: 'sftp_export_server',
-    name: 'Fulfilment XML Export',
-    settings: {
-      host: sftpHost,
-      port: sftpPort,
-      username: sftpUsername,
-      password: sftpPassword,
-    },
-  };
-
-  const sftp = new SftpDataSource(sftpConfig, log);
-
-  try {
-    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
-    const fileName = `fulfilment-${fulfilmentData.ref}-${timestamp}.xml`;
-    const remoteFilePath = `${sftpRemotePath}${fileName}`;
-
-    // ✅ CRITICAL FIX: Include options parameter
-    await sftp.uploadFile(remoteFilePath, xmlBuffer, {
-      overwrite: true,
-      createDirectories: true,
-    });
-
-    log.info('✅ [BACKGROUND] Fulfilment XML exported to SFTP', {
-      fulfilmentRef: fulfilmentData.ref,
-      remoteFilePath,
-      status: fulfilmentData.status,
-      fileSizeKB: Math.round(xmlBuffer.length / 1024),
-    });
-  } finally {
-    // ✅ CRITICAL: Always dispose SFTP connection
-    await sftp.dispose();
-    log.info('🔌 [BACKGROUND] SFTP connection disposed');
-  }
-}
-```
-
-### 5. Type Definitions (src/types/fulfilment.types.ts)
-
-```typescript
-/**
- * Type definitions for Rubix fulfilment webhooks and GraphQL responses
- */
-
-export interface RubixFulfilmentPayload {
-  id: string;
-  name: string;
-  accountId: string;
-  retailerId: string;
-  entityRef: string;
-  entityType: 'FULFILMENT';
-  entityStatus?: string;
-  type: 'NORMAL' | string;
-  rootEntityId?: string;
-  rootEntityType?: string;
-  rootEntityRef?: string;
-  attributes?: Record<string, any>;
-  context?: Record<string, any>;
-}
-
-export interface FulfilmentData {
-  id: string;
-  ref: string;
-  status: string;
-  deliveryType: string;
-  order?: {
-    id: string;
-    ref: string;
-    customer?: {
-      firstName: string;
-      lastName: string;
-      email: string;
-    };
-  };
-  items?: {
-    edges?: Array<{
-      node: {
-        id: string;
-        ref: string;
-        requestedQuantity?: number;
-        filledQuantity: number;
-        rejectedQuantity: number;
-        orderItem?: {
-          id: string;
-          ref: string;
-          productRef: string;
-          product?: {
-            name: string;
-          };
-        };
-      };
-    }>;
-  };
-  toAddress?: {
-    name?: string;
-    street?: string;
-    street2?: string;
-    city?: string;
-    state?: string;
-    postcode?: string;
-    country?: string;
-  };
-  fromAddress?: {
-    name?: string;
-    street?: string;
-    street2?: string;
-    city?: string;
-    state?: string;
-    postcode?: string;
-    country?: string;
-  };
-  createdOn: string;
-  updatedOn: string;
-}
-```
-
-### 6. Package Configuration (package.json)
-
-```json
-{
-  "name": "rubix-fulfilment-export",
-  "version": "2.0.0",
-  "description": "Rubix fulfilment webhook handler with SFTP XML export",
-  "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);
-
-// ❌ WRONG - No validation
-await client.setRetailerId(retailerId); // May be undefined!
-```
-
-**Why:** Missing retailerId causes 401 authentication errors with unclear messages.
-
-### Pattern 2: SFTP uploadFile with Options Parameter
-
-```typescript
-// ✅ CORRECT - Include options parameter
-await sftp.uploadFile(remoteFilePath, xmlBuffer, {
-  overwrite: true,
-  createDirectories: true,
-});
-
-// ❌ WRONG - Missing options (works but not explicit)
-await sftp.uploadFile(remoteFilePath, xmlBuffer);
-```
-
-**Why:** Explicit options make behavior clear and prevent production surprises.
-
-### Pattern 3: SDK Error Type Handling
-
-```typescript
-// ✅ CORRECT - Handle SDK error types
-import {
-  DataSourceError,
-  AuthenticationError,
-  GraphQLError,
-} from '@fluentcommerce/fc-connect-sdk';
-
-catch (error: unknown) {
-  if (error instanceof GraphQLError) {
-    errorCategory = 'GRAPHQL';
-    recommendation = 'Review query syntax';
-  } else if (error instanceof AuthenticationError) {
-    errorCategory = 'AUTHENTICATION';
-    recommendation = 'Verify credentials';
-  } else if (error instanceof DataSourceError) {
-    errorCategory = 'DATA_SOURCE';
-    recommendation = 'Check SFTP config';
-  }
-}
-
-// ❌ WRONG - Generic error handling
-catch (error: unknown) {
-  const message = error instanceof Error ? error.message : String(error);
-  // No categorization or recommendations
-}
-```
-
-**Why:** SDK errors include recommendations for resolution.
-
----
-
-## Testing
-
-### 1. Unit Tests
-
-```typescript
-// src/services/__tests__/fulfilment-query.test.ts
-import { processFulfilmentExport } from '../fulfilment-query.service';
-
-describe('Fulfilment Query Service', () => {
-  test('should export fulfilment successfully', async () => {
-    const mockCtx = {
-      log: { info: jest.fn(), error: jest.fn() },
-      activation: { getVariable: jest.fn() },
-    };
-
-    const payload = {
-      entityRef: 'FF-001',
-      entityType: 'FULFILMENT',
-      retailerId: '1',
-    };
-
-    await expect(processFulfilmentExport(mockCtx, payload)).resolves.not.toThrow();
-  });
-
-  test('should handle large fulfilment with pagination', async () => {
-    const mockCtx = {
-      log: { info: jest.fn(), error: jest.fn() },
-      activation: { getVariable: jest.fn() },
-    };
-
-    const payload = {
-      entityRef: 'FF-LARGE-001', // Fulfilment with 150 items
-      entityType: 'FULFILMENT',
-      retailerId: '1',
-    };
-
-    await expect(processFulfilmentExport(mockCtx, payload)).resolves.not.toThrow();
-
-    // Verify pagination was logged
-    expect(mockCtx.log.info).toHaveBeenCalledWith(
-      expect.stringContaining('Fulfilment and items queried successfully'),
-      expect.objectContaining({
-        itemCount: 150,
-        paginationUsed: true,
-      })
-    );
-  });
-});
-```
-
-### 2. Integration Test
-
-```bash
-# Test webhook with valid signature
-curl -X POST https://workspace.versori.run/rubix-fulfilment \
-  -H "Content-Type: application/json" \
-  -H "fluent-signature: <valid-signature>" \
-  -d '{
-    "entityType": "FULFILMENT",
-    "entityRef": "FF-001",
-    "retailerId": "1"
-  }'
-
-# Expected: 200 OK with { success: true, message: "..." }
-```
-
----
-
-## Production Checklist
-
-- [ ] Configure `fluentPublicKey` activation variable
-- [ ] Configure Fluent Commerce connection in Versori
-- [ ] Configure `sftp_export_server` connection in Versori (Basic Auth with username/password)
-- [ ] Set SFTP activation variables (host, port, remotePath)
-- [ ] Verify SFTP remote path exists and is writable
-- [ ] Create Rubix workflow with SendWebhook action (FULFILMENT events)
-- [ ] Build Event payload with entityRef, entityType, retailerId
-- [ ] Test webhook signature validation
-- [ ] Test GraphQL query with real fulfilment ref
-- [ ] **Test with large fulfilment (>100 items)** - Verify pagination works correctly
-- [ ] Test XML generation with special characters
-- [ ] Test SFTP upload and verify file on server
-- [ ] Test error scenarios (invalid signature, missing retailerId, SFTP failure)
-- [ ] Monitor response times (<100ms for validation)
-- [ ] Set up alerts for webhook/export failures
-- [ ] Document 3PL partner SFTP requirements
-- [ ] Test SFTP connection cleanup (check logs for dispose)
-- [ ] Verify pagination logs show correct item counts
-
----
-
-## 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 |
-| "Fulfilment not found" | Invalid ref or permissions | Verify fulfilment exists and user has query permissions |
-| "SFTP upload failed" | Connection/credentials | Test SFTP manually, verify credentials in connection and path |
-| "Failed to retrieve SFTP credentials" | Connection not configured | Ensure `sftp_export_server` connection exists with Basic Auth |
-| "SFTP connection pool exhausted" | Missing dispose() | Verify dispose() is in finally block |
-| "GraphQL query timeout" | Large dataset | Check pagination logs - pagination handles up to 1000 items |
-| "Missing items in XML" | Fulfilment >1000 items | Increase maxPages limit or implement chunked export |
-
----
-
-## Monitoring & Alerting
-
-### Success Response
-
-```json
-{
-  "success": true,
-  "entityType": "FULFILMENT",
-  "fulfilmentRef": "FF-001",
-  "message": "Webhook validated and export started in background",
-  "timestamp": "2025-01-25T14:30:00.000Z",
-  "correlationId": "act_123",
-  "processingMode": "async"
-}
-```
-
-### Key Metrics
-
-```typescript
-const METRICS = {
-  signatureValidationMs: 45,
-  totalResponseTimeMs: 50,
-  graphqlQueryMs: 1200,
-  xmlGenerationMs: 50,
-  sftpUploadMs: 980,
-  totalBackgroundMs: 2230,
-};
-```
-
----
-
-## Related Documentation
-
-- [Order Attribute Update Template](./template-webhook-rubix-order-attribute-update.md) - For ORDER webhooks
-- [Webhook Validation Guide](../../../../02-CORE-GUIDES/webhook-validation/)
-- [Versori Platform Guide](../../../../04-REFERENCE/platforms/versori/)
-- [SFTP Data Sources Guide](../../../../02-CORE-GUIDES/data-sources/)
-
----
-
-**Pattern**: Fulfilment webhook → GraphQL query → XML generation → SFTP upload
-**✅ Production-Ready**: Comprehensive template with all critical fixes applied
-**Key Learning**: Always validate retailerId, use proper SFTP options, handle SDK errors
-**Critical**: SFTP dispose() in finally block, retailerId validation, fire-and-forget pattern
+---
+template_id: tpl-webhook-rubix-fulfilment-export-inline
+canonical_filename: template-webhook-rubix-fulfilment-to-sftp-xml-inline.md
+version: 2.0.0
+sdk_version: ^0.1.39
+runtime: versori
+direction: webhook
+source: fluent-rubix-workflow
+destination: sftp-xml
+entity: fulfilment
+format: xml
+logging: versori
+status: stable
+pattern: inline-mapping
+features:
+  - webhook-validation
+  - fire-and-forget
+  - background-processing
+  - xml-export
+  - sftp-integration
+  - graphql-queries
+  - inline-mapping
+---
+
+# Template: Rubix Fulfilment Webhook → SFTP XML Export (Inline Mapping Pattern)
+
+**Template Version:** 2.0.0
+**SDK Version:** `^0.1.39` - `npm install @fluentcommerce/fc-connect-sdk@^0.1.39`
+**Last Updated:** 2025-11-12
+**Deployment Target:** Versori Platform
+**Mapping Pattern:** 🔵 **INLINE MAPPING** (Simpler, faster, webhook-optimized)
+
+> **📖 Pattern Selection Guide:**
+> - **Use THIS template (Inline)** for: Simple webhooks, tightly-coupled 3PL schemas, fast debugging
+> - **Use UniversalMapper version** for: Reusable configs, multi-environment deployments, complex transformations
+> - **See also:** [template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md](./template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md)
+
+**🆕 Version 2.0.0 - Production Ready:**
+- ✅ **Fulfilment-specific template** - Focused on 3PL/WMS integration
+- ✅ **Production-ready modular structure** - Separate workflows, services, types
+- ✅ **GraphQL fulfilment queries** - Fetch fulfilment + line items + order details
+- ✅ **Automatic pagination** - Handles fulfilments with 100+ items (up to 1000)
+- ✅ **XML generation** - Safe XML with automatic escaping
+- ✅ **SFTP upload** - Connection pooling with proper dispose()
+- ✅ **Critical fixes applied** - retailerId validation, SFTP options parameter, pagination
+- ✅ **Comprehensive documentation** - Testing, troubleshooting, monitoring
+
+---
+
+## Overview
+
+Receive fulfilment webhooks from Rubix workflows, query fulfilment details, generate XML, and upload to 3PL/WMS SFTP server.
+
+**Pattern:**
+1. Validate webhook signature (~10-50ms)
+2. Return HTTP 200 OK immediately (fast acknowledgment)
+3. Background: Query fulfilment details → Generate XML → Upload to SFTP (~2-5s)
+
+**Business Use Case:**
+- Rubix workflow sends webhook when fulfilment is created/updated
+- Handler queries fulfilment details (items, order, addresses)
+- Generates XML fulfillment notification for 3PL/WMS
+- Uploads to partner SFTP server for warehouse processing
+
+---
+
+## STEP 1: Understand This Template
+
+### What This Template Does
+
+**Core Functionality:**
+- Receives FULFILMENT webhooks from Fluent Commerce Rubix workflows
+- Validates webhook signature for security
+- Returns fast HTTP 200 OK response (<100ms)
+- Background: Queries fulfilment via GraphQL → Transforms to XML → Uploads to SFTP
+
+**Key SDK Components:**
+- `WebhookValidationService` - Signature validation with RSA/HMAC support
+- `createClient()` - Universal client factory (auto-detects Versori context)
+- `client.graphql()` - Query fulfilment details with automatic pagination
+- `XMLBuilder` - Safe XML generation with automatic escaping
+- `SftpDataSource` - SFTP operations with connection pooling
+- `ctx.credentials().getAccessToken()` - Retrieve SFTP credentials from Versori connection vault
+- Native Versori `log` - Structured logging from context
+
+**Pagination Support:**
+- Automatically handles fulfilments with 100+ line items
+- Uses two-query pattern: fulfilment details + paginated items
+- SDK auto-pagination: `pagination: { maxPages: 10 }` supports up to 1000 items
+- Logs pagination usage for monitoring
+
+**Critical Patterns:**
+- **Sync + Fire-and-Forget**: Fast validation, background processing
+- **Signature Validation**: Always validate `fluent-signature` or `flex.signature` headers
+- **Background Promises**: Use `.then().catch()` for error handling
+- **SFTP Credentials**: Retrieve from Versori connection vault (not activation variables)
+- **SFTP Cleanup**: Always call `dispose()` in finally blocks
+- **RetailerId Validation**: Check before `setRetailerId()` to prevent 401 errors
+
+### When to Use This Template
+
+✅ **USE THIS TEMPLATE FOR:**
+- Fulfilment created/updated webhooks from Rubix workflows
+- Export fulfilment details to 3PL/WMS via SFTP
+- Need XML format for warehouse management systems
+- Require signature validation for security
+- Need fast webhook acknowledgment + async processing
+
+❌ **DON'T USE FOR:**
+- Order webhooks (use order attribute update template)
+- Inventory webhooks (use inventory templates)
+- CSV/JSON exports (use format-specific templates)
+- Synchronous processing required (use standard http workflow)
+
+### Business Use Cases
+
+**Use Case: 3PL Warehouse Fulfillment Notification**
+- Rubix workflow sends webhook when fulfilment moves to "ALLOCATED" status
+- Handler queries fulfilment details (items, quantities, order info)
+- Generates XML fulfillment order for warehouse system
+- Uploads to 3PL SFTP server for pick/pack/ship processing
+- 3PL system imports XML and creates warehouse tasks
+
+---
+
+## 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 FULFILMENT events with signature validation, GraphQL queries, XML generation, and SFTP upload.
+
+REQUIREMENTS:
+1. Runtime: Versori Platform (HTTP webhook)
+2. Source: Rubix SendWebhook action (FULFILMENT entity type only)
+3. Destination: SFTP XML export to 3PL/WMS partner
+4. Format: XML with fulfilment details, line items, order info
+5. Entity: FULFILMENT
+
+KEY FEATURES:
+- Webhook signature validation using WebhookValidationService
+- Sync mode + fire-and-forget pattern for fast response
+- Background processing: GraphQL query → Inline XML mapping → XML generation → SFTP upload
+- **Automatic pagination** - Handles fulfilments with 100+ items (up to 1000 items)
+- Two-query pattern: Fulfilment details + paginated items query
+- **Inline XML mapping** - Manual object construction (simple, no config files)
+- **XMLBuilder** - Safe XML generation with automatic escaping
+- Modular architecture (workflows/, services/, types/)
+- Native Versori logging (no LoggingService)
+- SFTP cleanup with dispose() in finally blocks
+- 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 Queries: Two separate queries (fulfilment + items with pagination)
+6. Pagination: Use SDK automatic pagination with maxPages: 10, first: 100
+7. **Inline Mapping**: Manual object construction for XML structure (no external config)
+8. XML Generation: Use XMLBuilder with automatic escaping
+9. SFTP Upload: Include options parameter { overwrite: true, createDirectories: true }
+10. SFTP Cleanup: Always dispose() in finally block
+11. Error Handling: Import and handle DataSourceError, AuthenticationError, GraphQLError
+12. Type Safety: Use Logger, VersoriContext types (not any)
+
+SDK METHODS TO USE:
+- import { Buffer } from 'node:buffer' (CRITICAL for Versori/Deno)
+- 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, pagination: { maxPages: 10 } })
+- Manual object construction for XML structure (inline mapping)
+- new XMLBuilder({ prettyPrint: true, xmlDeclaration: true, encoding: 'UTF-8' })
+- xmlBuilder.build(xmlData, 'FulfilmentExport')
+- await ctx.credentials().getAccessToken('sftp_export_server') - Retrieve SFTP credentials from connection vault
+- Buffer.from(accessToken, 'base64').toString('utf-8') - Decode Basic Auth credentials
+- new SftpDataSource(config, log) - config includes connectionId: 'sftp_export_server'
+- await sftp.uploadFile(remotePath, buffer, { overwrite: true, createDirectories: true })
+- await sftp.dispose() (CRITICAL in finally block)
+
+FORBIDDEN PATTERNS:
+- ❌ LoggingService (use native log from context)
+- ❌ await on background processing (use fire-and-forget)
+- ❌ Missing dispose() for SFTP
+- ❌ Missing options parameter in uploadFile()
+- ❌ Missing retailerId validation before setRetailerId()
+- ❌ Storing SFTP credentials in activation variables (use Versori connection vault)
+- ❌ Using 'any' type (use Logger, VersoriContext from SDK)
+- ❌ Direct FluentClient instantiation (use createClient factory)
+- ❌ Generic error handling (use SDK error types)
+
+GRAPHQL QUERY STRUCTURE:
+
+**Single Query with Nested Items (Schema-Validated)**
+```graphql
+query GetFulfilment($id: ID!, $first: Int!, $after: String) {
+  fulfilment(id: $id) {
+    id
+    ref
+    status
+    deliveryType
+    order {
+      id
+      ref
+      customer { firstName, lastName, email }
+    }
+    toAddress {
+      name, street, street2, city, state, postcode, country
+    }
+    fromAddress {
+      name, street, street2, city, state, postcode, country
+    }
+    items(first: $first, after: $after) {
+      edges {
+        node {
+          id
+          ref
+          requestedQuantity
+          filledQuantity
+          rejectedQuantity
+          orderItem {
+            id
+            ref
+            productRef
+            product { name }
+          }
+        }
+        cursor
+      }
+      pageInfo {
+        hasNextPage
+      }
+    }
+    createdOn
+    updatedOn
+  }
+}
+```
+
+**Why Single Query?**
+- Items are nested under the fulfilment type in Fluent Commerce schema
+- Single query with `connectionPath: 'fulfilment.items'` for SDK pagination
+- SDK automatically handles pagination with `pagination: { maxPages: 10 }` config
+- More efficient than two separate queries (reduces GraphQL roundtrips)
+
+XML OUTPUT STRUCTURE:
+<FulfilmentExport>
+  <Fulfilment ref="FF-001" status="ALLOCATED">
+    <OrderRef>ORD-123</OrderRef>
+    <DeliveryType>STANDARD</DeliveryType>
+    <Customer>
+      <FirstName>John</FirstName>
+      <LastName>Smith</LastName>
+      <Email>john@example.com</Email>
+    </Customer>
+    <ToAddress>
+      <Name>John Smith</Name>
+      <Street>123 Main St</Street>
+      <Street2>Apt 4B</Street2>
+      <City>New York</City>
+      <State>NY</State>
+      <Postcode>10001</Postcode>
+      <Country>US</Country>
+    </ToAddress>
+    <FromAddress>
+      <Name>Warehouse</Name>
+      <Street>456 Warehouse St</Street>
+      <City>Chicago</City>
+      <State>IL</State>
+      <Postcode>60601</Postcode>
+      <Country>US</Country>
+    </FromAddress>
+    <Items>
+      <Item ref="FFI-001">
+        <ProductRef>SKU-001</ProductRef>
+        <ProductName>Widget</ProductName>
+        <RequestedQuantity>2</RequestedQuantity>
+        <FilledQuantity>2</FilledQuantity>
+        <RejectedQuantity>0</RejectedQuantity>
+      </Item>
+    </Items>
+    <CreatedOn>2025-01-25T10:00:00Z</CreatedOn>
+    <UpdatedOn>2025-01-25T11:00:00Z</UpdatedOn>
+  </Fulfilment>
+</FulfilmentExport>
+
+GENERATE:
+1. package.json with dependencies
+2. index.ts (entry point - exports workflow)
+3. src/workflows/webhook/fulfilment-export-handler.ts (webhook entry)
+4. src/services/fulfilment-query.service.ts (GraphQL queries)
+5. src/services/xml-export.service.ts (Inline XML mapping + XMLBuilder + SFTP upload)
+6. src/types/fulfilment.types.ts (TypeScript interfaces)
+7. readme.md with setup instructions
+
+Ensure all code is production-ready with proper error handling, signature validation, SFTP cleanup, inline XML mapping, and type safety.
+```
+
+---
+
+## STEP 3: Detailed Flow Documentation
+
+### Complete Processing Flow
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│ 1. RUBIX WEBHOOK RECEIVED                                   │
+│    POST https://{workspace}.versori.run/rubix-fulfilment    │
+│    Headers: fluent-signature                                │
+│    Body: { entityRef: "FF-001", entityType: "FULFILMENT" }  │
+└────────────────────┬────────────────────────────────────────┘
+                     │
+                     ▼
+┌─────────────────────────────────────────────────────────────┐
+│ 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 === 'FULFILMENT'                      │
+│    - 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 (~2-5 seconds)                     │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5a. Initialize Fluent Client (~100ms)               │  │
+│    │     - createClient({ ...ctx, log })                 │  │
+│    │     - Validate retailerId exists                    │  │
+│    │     - client.setRetailerId(retailerId)              │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5b. Query Fulfilment Details (~500-1500ms)          │  │
+│    │     - GraphQL query with nested fields              │  │
+│    │     - Fulfilment + items + order + addresses        │  │
+│    │     - Handle GraphQLError if query fails            │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5c. Generate XML (~50ms)                            │  │
+│    │     - Inline XML structure construction            │  │
+│    │     - XMLBuilder handles escaping automatically     │  │
+│    │     - Create Buffer from XML string                 │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5d. Upload to SFTP (~500-2000ms)                    │  │
+│    │     - Initialize SftpDataSource                     │  │
+│    │     - Upload with options parameter                 │  │
+│    │     - Handle DataSourceError if upload fails        │  │
+│    │     - ALWAYS dispose() in finally block             │  │
+│    └─────────────────────────────────────────────────────┘  │
+│    ┌─────────────────────────────────────────────────────┐  │
+│    │ 5e. Log Completion                                   │  │
+│    │     - Success: Log fulfilment 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 Query** | ~500-1500ms | ❌ No (background) |
+| **XML Generation** | ~50ms | ❌ No (background) |
+| **SFTP Upload** | ~500-2000ms | ❌ No (background) |
+| **Total Background** | ~2000-5000ms | ❌ Fire-and-forget |
+
+---
+
+## STEP 4: Production Modular Structure
+
+### Complete Project Structure
+
+```
+rubix-fulfilment-export/
+├── 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/
+    │       └── fulfilment-export-handler.ts  # Webhook entry point
+    │
+    ├── services/
+    │   ├── fulfilment-query.service.ts       # GraphQL queries
+    │   └── xml-export.service.ts             # Inline XML mapping + XMLBuilder + SFTP upload
+    │
+    └── types/
+        └── fulfilment.types.ts               # TypeScript interfaces
+```
+
+**Why This Structure?**
+- ✅ **Clear separation**: Webhook handlers vs business logic
+- ✅ **Reusable services**: Query and export logic can be unit tested
+- ✅ **Simple inline mapping**: XML structure defined directly in code (no config files)
+- ✅ **Type safety**: TypeScript interfaces for better IDE support
+- ✅ **Scalable**: Easy to add more fulfilment webhooks
+- ✅ **Testable**: Services can be mocked and tested independently
+- ✅ **Fast debugging**: XML structure visible directly in code
+
+---
+
+## SDK Imports (Verified - Versori Optimized)
+
+```typescript
+// CRITICAL: Buffer import required for Versori/Deno runtime
+import { Buffer } from 'node:buffer';
+
+// FC Connect SDK imports
+import {
+  createClient,
+  WebhookValidationService,
+  XMLBuilder,
+  SftpDataSource,
+  DataSourceError,
+  AuthenticationError,
+  GraphQLError,
+  type Logger,
+  type VersoriContext,
+} from '@fluentcommerce/fc-connect-sdk';
+
+// Versori platform imports
+import { webhook } from '@versori/run';
+import type { Context } from '@versori/run';
+```
+
+---
+
+## Configuration
+
+### Activation Variables
+
+```json
+{
+  "fluentPublicKey": "-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----",
+  "sftpHost": "sftp.3pl-partner.com",
+  "sftpPort": 22,
+  "sftpRemotePath": "/incoming/fulfilments/"
+}
+```
+
+> **Important:** `sftpUsername` and `sftpPassword` are **NOT** stored in activation variables. They are securely retrieved from the `sftp_export_server` connection vault at runtime. See the SFTP Credential Management section below for details.
+
+### Connections
+
+| Connection | Description | Required |
+|------------|-------------|----------|
+| `fluent_commerce` | OAuth2 connection to Fluent Commerce | Yes |
+| `sftp_export_server` | Basic Auth connection for SFTP credentials (username/password) | Yes |
+
+## SFTP Credential Management
+
+Fetch credentials securely from Versori connection vault using `ctx.credentials().getAccessToken()`:
+
+**Benefits:**
+- ✅ Credentials stored securely in Versori vault
+- ✅ Centralized management - update in one place
+- ✅ Access control enforced by platform
+- ✅ No credentials in activation variables
+- ✅ Explicit error handling with validation
+
+### Setup Steps
+
+1. In Versori Dashboard → Connections → Add Connection
+2. Name: `sftp_export_server`
+3. Type: Basic Auth
+4. Enter SFTP username and password
+5. Save connection
+6. Reference in code: `ctx.credentials().getAccessToken('sftp_export_server')`
+
+---
+
+## Complete Working Code
+
+### 1. Entry Point (index.ts)
+
+```typescript
+/**
+ * Entry point - Export webhook workflow for Versori platform
+ */
+
+export { rubixFulfilmentExportHandler } from './src/workflows/webhook/fulfilment-export-handler';
+```
+
+### 2. Webhook Handler (src/workflows/webhook/fulfilment-export-handler.ts)
+
+```typescript
+/**
+ * Rubix Fulfilment Webhook Handler → SFTP XML Export
+ *
+ * Direction: Fluent Rubix Workflow (FULFILMENT) → Versori → GraphQL → XML → SFTP
+ */
+
+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 { processFulfilmentExport } from '../../services/fulfilment-query.service';
+
+export const rubixFulfilmentExportHandler = webhook('rubix-fulfilment', {
+  response: { mode: 'sync' }, // ✅ Sync mode: response sent when handler returns
+}, async (ctx: Context<any>) => {
+  const { log, activation } = ctx;
+
+  log.info('🚀 [WEBHOOK] Received Rubix fulfilment 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 fulfilment ref',
+      },
+    };
+  }
+
+  if (entityType !== 'FULFILMENT') {
+    log.error('❌ [WEBHOOK] Invalid entity type', { entityType, expected: 'FULFILMENT' });
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: `Invalid entity type: ${entityType}. Expected: FULFILMENT`,
+        recommendation: 'Use order-attribute-update template for ORDER 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
+  processFulfilmentExport(ctx, payload)
+    .then(() => {
+      log.info('✅ [BACKGROUND] Fulfilment exported successfully', {
+        fulfilmentRef: entityRef,
+      });
+    })
+    .catch((error: unknown) => {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      log.error('❌ [BACKGROUND] Fulfilment export failed', {
+        fulfilmentRef: 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,
+      fulfilmentRef: entityRef,
+      message: 'Webhook validated and export started in background',
+      timestamp: new Date().toISOString(),
+      correlationId: activation?.id,
+    },
+  };
+});
+```
+
+### 3. Fulfilment Query Service (src/services/fulfilment-query.service.ts)
+
+```typescript
+/**
+ * Fulfilment Query Service
+ *
+ * Handles GraphQL queries for fulfilment details and orchestrates XML export
+ */
+
+import {
+  createClient,
+  DataSourceError,
+  AuthenticationError,
+  GraphQLError,
+  type Logger,
+  type VersoriContext,
+} from '@fluentcommerce/fc-connect-sdk';
+import { exportFulfilmentToSFTP } from './xml-export.service';
+import type { RubixFulfilmentPayload, FulfilmentData } from '../types/fulfilment.types';
+
+// Single query with nested items (schema-validated structure)
+const FULFILMENT_QUERY = `
+  query GetFulfilment($id: ID!, $first: Int!, $after: String) {
+    fulfilment(id: $id) {
+      id
+      ref
+      status
+      deliveryType
+      order {
+        id
+        ref
+        customer {
+          firstName
+          lastName
+          email
+        }
+      }
+      toAddress {
+        name
+        street
+        street2
+        city
+        state
+        postcode
+        country
+      }
+      fromAddress {
+        name
+        street
+        street2
+        city
+        state
+        postcode
+        country
+      }
+      items(first: $first, after: $after) {
+        edges {
+          node {
+            id
+            ref
+            requestedQuantity
+            filledQuantity
+            rejectedQuantity
+            orderItem {
+              id
+              ref
+              productRef
+              product {
+                name
+              }
+            }
+          }
+          cursor
+        }
+        pageInfo {
+          hasNextPage
+        }
+      }
+      createdOn
+      updatedOn
+    }
+  }
+`;
+
+export async function processFulfilmentExport(
+  ctx: VersoriContext,
+  payload: RubixFulfilmentPayload
+): Promise<void> {
+  const log = ctx.log as Logger;
+  const { entityRef, retailerId } = payload;
+
+  const processingStartTime = Date.now();
+
+  log.info('🔄 [BACKGROUND] Starting fulfilment export', {
+    timestamp: new Date().toISOString(),
+    fulfilmentRef: entityRef,
+  });
+
+  try {
+    // ========================================
+    // STEP 1: VALIDATE RETAILER ID
+    // ========================================
+
+    if (!retailerId) {
+      log.error('❌ [BACKGROUND] Missing retailerId in payload', {
+        fulfilmentRef: 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: QUERY FULFILMENT WITH NESTED ITEMS
+    // ========================================
+
+    log.info('🔍 [BACKGROUND] Querying fulfilment with items', { fulfilmentRef: entityRef });
+
+    const result = await client.graphql({
+      query: FULFILMENT_QUERY,
+      variables: {
+        id: entityRef,  // ✅ Use 'id' parameter (schema-validated)
+        first: 100,
+      },
+      pagination: {
+        connectionPath: 'fulfilment.items',  // ✅ Nested connection pagination
+        maxPages: 10, // Handles up to 1000 items (100 per page × 10 pages)
+      },
+    });
+
+    const fulfilmentData = result.data?.fulfilment as FulfilmentData | null;
+
+    if (!fulfilmentData) {
+      log.error('❌ [BACKGROUND] Fulfilment not found', { fulfilmentRef: entityRef });
+      throw new Error(`Fulfilment not found: ${entityRef}`);
+    }
+
+    const itemCount = fulfilmentData.items?.edges?.length || 0;
+
+    log.info('✅ [BACKGROUND] Fulfilment and items queried successfully', {
+      fulfilmentRef: fulfilmentData.ref,
+      status: fulfilmentData.status,
+      itemCount,
+      orderRef: fulfilmentData.order?.ref,
+      paginationUsed: result.metadata?.totalPages > 1,
+    });
+
+    // ========================================
+    // STEP 5: EXPORT TO SFTP
+    // ========================================
+
+    await exportFulfilmentToSFTP(ctx, completeFullfilmentData, log);
+
+    const duration = Date.now() - processingStartTime;
+    log.info('✅ [BACKGROUND] Fulfilment export completed', {
+      fulfilmentRef: 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 query 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 DataSourceError) {
+      errorMessage = error.message;
+      recommendation = 'Check SFTP configuration and connectivity';
+      errorCategory = 'DATA_SOURCE';
+    } else if (error instanceof Error) {
+      errorMessage = error.message;
+    } else {
+      errorMessage = String(error);
+    }
+
+    log.error('❌ [BACKGROUND] Fulfilment export failed', {
+      fulfilmentRef: entityRef,
+      error: errorMessage,
+      errorCategory,
+      recommendation,
+      stack: error instanceof Error ? error.stack : undefined,
+      errorType: error instanceof Error ? error.constructor.name : typeof error,
+    });
+
+    throw error;
+  }
+}
+```
+
+### 4. XML Export Service (src/services/xml-export.service.ts)
+
+```typescript
+/**
+ * XML Export Service
+ *
+ * Handles XML generation and SFTP upload for fulfilment exports
+ * Uses inline mapping (manual object construction) for XML structure
+ */
+
+import { Buffer } from 'node:buffer';
+import {
+  XMLBuilder,
+  SftpDataSource,
+  type Logger,
+  type VersoriContext,
+} from '@fluentcommerce/fc-connect-sdk';
+import type { FulfilmentData } from '../types/fulfilment.types';
+
+export async function exportFulfilmentToSFTP(
+  ctx: VersoriContext,
+  fulfilmentData: FulfilmentData,
+  log: Logger
+): Promise<void> {
+  const { activation } = ctx;
+
+  log.info('📝 [BACKGROUND] Generating XML for fulfilment', {
+    fulfilmentRef: fulfilmentData.ref,
+  });
+
+  // ========================================
+  // STEP 1: BUILD XML STRUCTURE (INLINE MAPPING)
+  // ========================================
+
+  const xmlBuilder = new XMLBuilder({
+    prettyPrint: true,
+    xmlDeclaration: true,
+    encoding: 'UTF-8',
+  });
+
+  // Inline XML structure construction
+  const xmlData = {
+    Fulfilment: {
+      '@ref': fulfilmentData.ref,
+      '@status': fulfilmentData.status,
+      OrderRef: fulfilmentData.order?.ref || '',
+      DeliveryType: fulfilmentData.deliveryType || '',
+      Customer: fulfilmentData.order?.customer
+        ? {
+            FirstName: fulfilmentData.order.customer.firstName || '',
+            LastName: fulfilmentData.order.customer.lastName || '',
+            Email: fulfilmentData.order.customer.email || '',
+          }
+        : {},
+      ToAddress: fulfilmentData.toAddress
+        ? {
+            Name: fulfilmentData.toAddress.name || '',
+            Street: fulfilmentData.toAddress.street || '',
+            Street2: fulfilmentData.toAddress.street2 || '',
+            City: fulfilmentData.toAddress.city || '',
+            State: fulfilmentData.toAddress.state || '',
+            Postcode: fulfilmentData.toAddress.postcode || '',
+            Country: fulfilmentData.toAddress.country || '',
+          }
+        : {},
+      FromAddress: fulfilmentData.fromAddress
+        ? {
+            Name: fulfilmentData.fromAddress.name || '',
+            Street: fulfilmentData.fromAddress.street || '',
+            Street2: fulfilmentData.fromAddress.street2 || '',
+            City: fulfilmentData.fromAddress.city || '',
+            State: fulfilmentData.fromAddress.state || '',
+            Postcode: fulfilmentData.fromAddress.postcode || '',
+            Country: fulfilmentData.fromAddress.country || '',
+          }
+        : {},
+      Items: {
+        Item:
+          fulfilmentData.items?.edges?.map(edge => ({
+            '@ref': edge.node.ref,
+            ProductRef: edge.node.orderItem?.productRef || '',
+            ProductName: edge.node.orderItem?.product?.name || '',
+            RequestedQuantity: edge.node.requestedQuantity || 0,
+            FilledQuantity: edge.node.filledQuantity,
+            RejectedQuantity: edge.node.rejectedQuantity,
+          })) || [],
+      },
+      CreatedOn: fulfilmentData.createdOn,
+      UpdatedOn: fulfilmentData.updatedOn,
+    },
+  };
+
+  const xmlString = xmlBuilder.build(xmlData, 'FulfilmentExport');
+  const xmlBuffer = Buffer.from(xmlString, 'utf8');
+
+  log.info('✅ [BACKGROUND] XML generated successfully', {
+    fulfilmentRef: fulfilmentData.ref,
+    xmlSizeBytes: xmlBuffer.length,
+    xmlSizeKB: Math.round(xmlBuffer.length / 1024),
+  });
+
+  // ========================================
+  // STEP 2: UPLOAD TO SFTP
+  // ========================================
+
+  log.info('📤 [BACKGROUND] Preparing SFTP upload', {
+    fulfilmentRef: fulfilmentData.ref,
+  });
+
+  // ========================================
+  // SFTP CREDENTIAL RETRIEVAL
+  // ========================================
+
+  /**
+   * Retrieve SFTP credentials from connection configuration
+   * 
+   * Connection Name: 'sftp_export_server' (must match the connection name in Versori UI)
+   * Auth Type: Basic Authentication (username + password)
+   */
+  log.info('🔐 [BACKGROUND] Retrieving SFTP credentials from connection configuration');
+
+  let sftpUsername: string;
+  let sftpPassword: string;
+
+  try {
+    // Retrieve credentials from the 'sftp_export_server' connection
+    const sftpCred = await ctx.credentials().getAccessToken('sftp_export_server');
+
+    if (!sftpCred?.accessToken) {
+      throw new Error('No SFTP credentials found in connection configuration');
+    }
+
+    // Decode base64 accessToken to get "username:password"
+    const rawBasicAuth = Buffer.from(sftpCred.accessToken, 'base64').toString('utf-8');
+
+    // Split on ':' to extract username and password
+    const parts = rawBasicAuth.split(':');
+
+    if (parts.length !== 2) {
+      throw new Error('Invalid SFTP credential format - expected username:password');
+    }
+
+    sftpUsername = parts[0];
+    sftpPassword = parts[1];
+
+    log.info('✅ [BACKGROUND] SFTP credentials retrieved successfully', {
+      hasUsername: !!sftpUsername,
+      hasPassword: !!sftpPassword,
+      usernameLength: sftpUsername.length,
+      passwordLength: sftpPassword.length,
+    });
+  } catch (error: any) {
+    log.error('❌ [BACKGROUND] Failed to retrieve SFTP credentials', {
+      message: error instanceof Error ? error.message : String(error),
+      stack: error instanceof Error ? error.stack : undefined,
+      errorType: error instanceof Error ? error.constructor.name : 'Error',
+      recommendation: 'Please ensure the SFTP connection "sftp_export_server" is configured in the Connections section with Basic Authentication (username and password)',
+    });
+    throw new Error(
+      `Failed to retrieve SFTP credentials from connection configuration: ${error instanceof Error ? error.message : String(error)}. ` +
+      'Please ensure the SFTP connection is configured in the Connections section with Basic Authentication (username and password)'
+    );
+  }
+
+  // Get SFTP configuration from activation variables
+  const sftpHost = activation.getVariable('sftpHost');
+  const sftpPort = parseInt(activation.getVariable('sftpPort') || '22', 10);
+  const sftpRemotePath = activation.getVariable('sftpRemotePath') || '/incoming/fulfilments/';
+
+  if (!sftpHost) {
+    log.error('⚠️ [BACKGROUND] SFTP configuration missing', {
+      recommendation: 'Configure sftpHost activation variable',
+      fulfilmentRef: fulfilmentData.ref,
+    });
+    throw new Error('SFTP configuration missing: sftpHost is required');
+  }
+
+  const sftpConfig = {
+    type: 'SFTP_XML' as const,
+    connectionId: 'sftp_export_server',
+    name: 'Fulfilment XML Export',
+    settings: {
+      host: sftpHost,
+      port: sftpPort,
+      username: sftpUsername,
+      password: sftpPassword,
+    },
+  };
+
+  const sftp = new SftpDataSource(sftpConfig, log);
+
+  try {
+    const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const fileName = `fulfilment-${fulfilmentData.ref}-${timestamp}.xml`;
+    const remoteFilePath = `${sftpRemotePath}${fileName}`;
+
+    // ✅ CRITICAL FIX: Include options parameter
+    await sftp.uploadFile(remoteFilePath, xmlBuffer, {
+      overwrite: true,
+      createDirectories: true,
+    });
+
+    log.info('✅ [BACKGROUND] Fulfilment XML exported to SFTP', {
+      fulfilmentRef: fulfilmentData.ref,
+      remoteFilePath,
+      status: fulfilmentData.status,
+      fileSizeKB: Math.round(xmlBuffer.length / 1024),
+    });
+  } finally {
+    // ✅ CRITICAL: Always dispose SFTP connection
+    await sftp.dispose();
+    log.info('🔌 [BACKGROUND] SFTP connection disposed');
+  }
+}
+```
+
+### 5. Type Definitions (src/types/fulfilment.types.ts)
+
+```typescript
+/**
+ * Type definitions for Rubix fulfilment webhooks and GraphQL responses
+ */
+
+export interface RubixFulfilmentPayload {
+  id: string;
+  name: string;
+  accountId: string;
+  retailerId: string;
+  entityRef: string;
+  entityType: 'FULFILMENT';
+  entityStatus?: string;
+  type: 'NORMAL' | string;
+  rootEntityId?: string;
+  rootEntityType?: string;
+  rootEntityRef?: string;
+  attributes?: Record<string, any>;
+  context?: Record<string, any>;
+}
+
+export interface FulfilmentData {
+  id: string;
+  ref: string;
+  status: string;
+  deliveryType: string;
+  order?: {
+    id: string;
+    ref: string;
+    customer?: {
+      firstName: string;
+      lastName: string;
+      email: string;
+    };
+  };
+  items?: {
+    edges?: Array<{
+      node: {
+        id: string;
+        ref: string;
+        requestedQuantity?: number;
+        filledQuantity: number;
+        rejectedQuantity: number;
+        orderItem?: {
+          id: string;
+          ref: string;
+          productRef: string;
+          product?: {
+            name: string;
+          };
+        };
+      };
+    }>;
+  };
+  toAddress?: {
+    name?: string;
+    street?: string;
+    street2?: string;
+    city?: string;
+    state?: string;
+    postcode?: string;
+    country?: string;
+  };
+  fromAddress?: {
+    name?: string;
+    street?: string;
+    street2?: string;
+    city?: string;
+    state?: string;
+    postcode?: string;
+    country?: string;
+  };
+  createdOn: string;
+  updatedOn: string;
+}
+```
+
+### 6. Package Configuration (package.json)
+
+```json
+{
+  "name": "rubix-fulfilment-export",
+  "version": "2.0.0",
+  "description": "Rubix fulfilment webhook handler with SFTP XML export",
+  "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);
+
+// ❌ WRONG - No validation
+await client.setRetailerId(retailerId); // May be undefined!
+```
+
+**Why:** Missing retailerId causes 401 authentication errors with unclear messages.
+
+### Pattern 2: SFTP uploadFile with Options Parameter
+
+```typescript
+// ✅ CORRECT - Include options parameter
+await sftp.uploadFile(remoteFilePath, xmlBuffer, {
+  overwrite: true,
+  createDirectories: true,
+});
+
+// ❌ WRONG - Missing options (works but not explicit)
+await sftp.uploadFile(remoteFilePath, xmlBuffer);
+```
+
+**Why:** Explicit options make behavior clear and prevent production surprises.
+
+### Pattern 3: SDK Error Type Handling
+
+```typescript
+// ✅ CORRECT - Handle SDK error types
+import {
+  DataSourceError,
+  AuthenticationError,
+  GraphQLError,
+} from '@fluentcommerce/fc-connect-sdk';
+
+catch (error: unknown) {
+  if (error instanceof GraphQLError) {
+    errorCategory = 'GRAPHQL';
+    recommendation = 'Review query syntax';
+  } else if (error instanceof AuthenticationError) {
+    errorCategory = 'AUTHENTICATION';
+    recommendation = 'Verify credentials';
+  } else if (error instanceof DataSourceError) {
+    errorCategory = 'DATA_SOURCE';
+    recommendation = 'Check SFTP config';
+  }
+}
+
+// ❌ WRONG - Generic error handling
+catch (error: unknown) {
+  const message = error instanceof Error ? error.message : String(error);
+  // No categorization or recommendations
+}
+```
+
+**Why:** SDK errors include recommendations for resolution.
+
+---
+
+## Testing
+
+### 1. Unit Tests
+
+```typescript
+// src/services/__tests__/fulfilment-query.test.ts
+import { processFulfilmentExport } from '../fulfilment-query.service';
+
+describe('Fulfilment Query Service', () => {
+  test('should export fulfilment successfully', async () => {
+    const mockCtx = {
+      log: { info: jest.fn(), error: jest.fn() },
+      activation: { getVariable: jest.fn() },
+    };
+
+    const payload = {
+      entityRef: 'FF-001',
+      entityType: 'FULFILMENT',
+      retailerId: '1',
+    };
+
+    await expect(processFulfilmentExport(mockCtx, payload)).resolves.not.toThrow();
+  });
+
+  test('should handle large fulfilment with pagination', async () => {
+    const mockCtx = {
+      log: { info: jest.fn(), error: jest.fn() },
+      activation: { getVariable: jest.fn() },
+    };
+
+    const payload = {
+      entityRef: 'FF-LARGE-001', // Fulfilment with 150 items
+      entityType: 'FULFILMENT',
+      retailerId: '1',
+    };
+
+    await expect(processFulfilmentExport(mockCtx, payload)).resolves.not.toThrow();
+
+    // Verify pagination was logged
+    expect(mockCtx.log.info).toHaveBeenCalledWith(
+      expect.stringContaining('Fulfilment and items queried successfully'),
+      expect.objectContaining({
+        itemCount: 150,
+        paginationUsed: true,
+      })
+    );
+  });
+});
+```
+
+### 2. Integration Test
+
+```bash
+# Test webhook with valid signature
+curl -X POST https://workspace.versori.run/rubix-fulfilment \
+  -H "Content-Type: application/json" \
+  -H "fluent-signature: <valid-signature>" \
+  -d '{
+    "entityType": "FULFILMENT",
+    "entityRef": "FF-001",
+    "retailerId": "1"
+  }'
+
+# Expected: 200 OK with { success: true, message: "..." }
+```
+
+---
+
+## Production Checklist
+
+- [ ] Configure `fluentPublicKey` activation variable
+- [ ] Configure Fluent Commerce connection in Versori
+- [ ] Configure `sftp_export_server` connection in Versori (Basic Auth with username/password)
+- [ ] Set SFTP activation variables (host, port, remotePath)
+- [ ] Verify SFTP remote path exists and is writable
+- [ ] Create Rubix workflow with SendWebhook action (FULFILMENT events)
+- [ ] Build Event payload with entityRef, entityType, retailerId
+- [ ] Test webhook signature validation
+- [ ] Test GraphQL query with real fulfilment ref
+- [ ] **Test with large fulfilment (>100 items)** - Verify pagination works correctly
+- [ ] Test XML generation with special characters
+- [ ] Test SFTP upload and verify file on server
+- [ ] Test error scenarios (invalid signature, missing retailerId, SFTP failure)
+- [ ] Monitor response times (<100ms for validation)
+- [ ] Set up alerts for webhook/export failures
+- [ ] Document 3PL partner SFTP requirements
+- [ ] Test SFTP connection cleanup (check logs for dispose)
+- [ ] Verify pagination logs show correct item counts
+
+---
+
+## 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 |
+| "Fulfilment not found" | Invalid ref or permissions | Verify fulfilment exists and user has query permissions |
+| "SFTP upload failed" | Connection/credentials | Test SFTP manually, verify credentials in connection and path |
+| "Failed to retrieve SFTP credentials" | Connection not configured | Ensure `sftp_export_server` connection exists with Basic Auth |
+| "SFTP connection pool exhausted" | Missing dispose() | Verify dispose() is in finally block |
+| "GraphQL query timeout" | Large dataset | Check pagination logs - pagination handles up to 1000 items |
+| "Missing items in XML" | Fulfilment >1000 items | Increase maxPages limit or implement chunked export |
+
+---
+
+## Monitoring & Alerting
+
+### Success Response
+
+```json
+{
+  "success": true,
+  "entityType": "FULFILMENT",
+  "fulfilmentRef": "FF-001",
+  "message": "Webhook validated and export started in background",
+  "timestamp": "2025-01-25T14:30:00.000Z",
+  "correlationId": "act_123",
+  "processingMode": "async"
+}
+```
+
+### Key Metrics
+
+```typescript
+const METRICS = {
+  signatureValidationMs: 45,
+  totalResponseTimeMs: 50,
+  graphqlQueryMs: 1200,
+  xmlGenerationMs: 50,
+  sftpUploadMs: 980,
+  totalBackgroundMs: 2230,
+};
+```
+
+---
+
+## Related Documentation
+
+- [Order Attribute Update Template](./template-webhook-rubix-order-attribute-update.md) - For ORDER webhooks
+- [Webhook Validation Guide](../../../../02-CORE-GUIDES/webhook-validation/)
+- [Versori Platform Guide](../../../../04-REFERENCE/platforms/versori/)
+- [SFTP Data Sources Guide](../../../../02-CORE-GUIDES/data-sources/)
+
+---
+
+**Pattern**: Fulfilment webhook → GraphQL query → XML generation → SFTP upload
+**✅ Production-Ready**: Comprehensive template with all critical fixes applied
+**Key Learning**: Always validate retailerId, use proper SFTP options, handle SDK errors
+**Critical**: SFTP dispose() in finally block, retailerId validation, fire-and-forget pattern