@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.56

package/docs/01-TEMPLATES/versori/workflows/rubix-webhooks/rubix-webhooks-guide.md

@@ -1,520 +1,520 @@
-# Rubix Webhook Templates
-
-> **Templates for receiving webhooks from Fluent Commerce Rubix workflows**
-> Complete pattern: Rubix → Versori → Validate → Query/Mutate → Logic → Output
-
-## Overview
-
-This directory contains templates demonstrating how to receive webhooks from Fluent Commerce Rubix workflows, validate signatures, and perform entity-specific operations (GraphQL queries, mutations, SFTP exports).
-
-## Pattern Flow
-
-```
-┌─────────────────┐
-│ Rubix Workflow  │
-│ (Fluent Commerce)│
-└────────┬─────────┘
-         │
-         │ HTTP POST with signature
-         │ Payload: { entityRef, entityType, retailerId }
-         ▼
-┌─────────────────────────────────────┐
-│ Versori Webhook Endpoint            │
-│ 1. Validate signature (sync)        │
-│ 2. Extract entity ref               │
-│ 3. Return HTTP 200 OK immediately   │
-│                                     │
-│ Background (fire-and-forget):       │
-│ 4. Query/mutate Fluent via GraphQL  │
-│ 5. Perform business logic           │
-│ 6. Export to SFTP (if applicable)   │
-└─────────────────────────────────────┘
-```
-
-## Available Templates
-
-| Template | Entity | Destination | Complexity | Status | Use Case |
-|----------|--------|-------------|------------|--------|----------|
-| **[Fulfilment → SFTP XML (Inline)](./template-webhook-rubix-fulfilment-to-sftp-xml-inline.md)** | FULFILMENT | SFTP + XML | Medium | ✅ Production Ready | Export fulfilment details to 3PL/WMS partner via SFTP when fulfilment is created/updated (inline mapping) |
-| **[Fulfilment → SFTP XML (UniversalMapper)](./template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md)** | FULFILMENT | SFTP + XML | Medium | ✅ Production Ready | Export fulfilment details to 3PL/WMS partner via SFTP when fulfilment is created/updated (external JSON mapping) |
-| **[Order → Attribute Update](./template-webhook-rubix-order-attribute-update.md)** | ORDER | GraphQL | Simple | ✅ Production Ready | Update order attributes when order status changes in Rubix workflow |
-
-## Template Selection Guide
-
-### When to Use Fulfilment → SFTP XML
-
-✅ **Use this template if:**
-- Receiving FULFILMENT webhooks from Rubix workflows
-- Need to export fulfilment details to external systems
-- 3PL/WMS requires XML format via SFTP
-- Need fulfilment + line items + order + address details
-- Require warehouse management system integration
-
-**What it does:**
-1. Validates webhook signature (fast, ~50ms response)
-2. Background: Queries fulfilment details via GraphQL
-3. Generates XML with XMLBuilder (automatic escaping)
-4. Uploads to 3PL SFTP server
-5. Always cleans up SFTP connections
-
-**Key Features:**
-- GraphQL queries (fulfilment + nested fields)
-- XML generation with safe escaping
-- SFTP upload with connection pooling
-- Comprehensive error handling (GraphQL, SFTP errors)
-
-**Two Mapping Patterns Available:**
-
-The Fulfilment → SFTP XML template comes in **two versions** - choose based on your needs:
-
-| Pattern | File | Best For |
-|---------|------|----------|
-| **🔵 Inline Mapping** | [template-webhook-rubix-fulfilment-to-sftp-xml-inline.md](./template-webhook-rubix-fulfilment-to-sftp-xml-inline.md) | Simple webhooks, fast debugging, tightly-coupled schemas |
-| **🟢 UniversalMapper** | [template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md](./template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md) | Reusable configs, multi-environment, complex transformations |
-
-**Quick Decision Guide:**
-- **Use Inline** if: Simple XML structure (<20 fields), rarely changes, single environment, rapid prototyping
-- **Use UniversalMapper** if: Complex XML (>20 fields), frequent changes, multi-environment (dev/staging/prod), need SDK resolvers
-
-See [Mapping Pattern Comparison](#mapping-pattern-comparison) below for detailed comparison.
-
----
-
-### When to Use Order → Attribute Update
-
-✅ **Use this template if:**
-- Receiving ORDER webhooks from Rubix workflows
-- Need to update order custom attributes
-- Simple attribute updates without external systems
-- No SFTP/S3 export required
-
-**What it does:**
-1. Validates webhook signature (fast, ~50ms response)
-2. Background: Updates order attributes via GraphQL mutation
-3. Records processing timestamp
-4. No external system integration
-
-**Key Features:**
-- GraphQL mutations (attribute updates)
-- Lightweight (no SFTP/XML complexity)
-- Fast background processing (~300-500ms)
-- Simplified error handling
-
----
-
-## Key Concepts
-
-### Rubix Workflow Configuration
-
-Rubix workflows in Fluent Commerce can call external webhook endpoints. When configuring a Rubix workflow:
-
-1. **Add SendWebhook Action** - Configure to call Versori webhook endpoint
-2. **Set Webhook URL** - Your Versori endpoint URL:
-   - Fulfilment: `https://{workspace}.versori.run/rubix-fulfilment`
-   - Order: `https://{workspace}.versori.run/rubix-order`
-3. **Build Event Payload** - Include:
-   - `entityRef` - Entity reference (required)
-   - `entityType` - "FULFILMENT" or "ORDER" (required)
-   - `retailerId` - Retailer ID (required for GraphQL)
-   - Additional context fields as needed
-4. **Signature Headers** - Automatically included by Fluent Commerce (`fluent-signature`, `flex.signature`)
-
-### Versori Webhook Handler
-
-Both templates follow the same core pattern:
-- **Validates webhook signature** using `WebhookValidationService` (synchronously, ~10-50ms)
-- **Returns fast response** using `mode: 'sync'` + fire-and-forget pattern (~50ms)
-- **Processes in background** without blocking response (GraphQL, SFTP, etc.)
-- **Validates retailerId** before `setRetailerId()` to prevent 401 errors
-- **Handles SDK errors** (GraphQLError, AuthenticationError, DataSourceError)
-
-**Critical Pattern:**
-- ✅ Webhook handler uses `response: { mode: 'sync' }` directly (no `.then(http())`)
-- ✅ Signature validation happens synchronously in webhook handler
-- ✅ Background processing uses fire-and-forget (no `await` on background promise)
-- ❌ **DO NOT** use `.then(http())` pattern - it creates unnecessary chaining
-
-### Differences Between Templates
-
-| Aspect | Fulfilment → SFTP XML | Order → Attribute Update |
-|--------|------------------------|--------------------------|
-| **Entity Type** | FULFILMENT | ORDER |
-| **GraphQL Operation** | Query (fetch details) | Mutation (update attributes) |
-| **Data Transformation** | ✅ XML generation | ❌ None |
-| **External System** | ✅ SFTP upload | ❌ None |
-| **SFTP Cleanup** | ✅ dispose() required | ❌ N/A |
-| **Complexity** | Medium (query + XML + SFTP) | Simple (mutation only) |
-| **Background Time** | ~2-5s | ~300-500ms |
-| **Use Case** | 3PL/WMS integration | Order tracking |
-
----
-
-## Common Configuration
-
-### Activation Variables (All Templates)
-
-```json
-{
-  "fluentPublicKey": "-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----"
-}
-```
-
-### Additional for Fulfilment → SFTP XML
-
-```json
-{
-  "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 SFTP Credential Management section below).
-
-### Versori Connections (Required for All)
-
-| Connection | Description |
-|------------|-------------|
-| `fluent_commerce` | OAuth2 connection to Fluent Commerce API |
-| `sftp_export_server` | Basic Auth connection for SFTP credentials (username/password) - Required for Fulfilment templates |
-
-## SFTP Credential Management
-
-**For Fulfilment → SFTP XML templates:**
-
-SFTP credentials (username/password) are stored securely in Versori connection vault, not in activation variables.
-
-**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. Code automatically retrieves credentials using `ctx.credentials().getAccessToken('sftp_export_server')`
-
-**Activation Variables (for SFTP):**
-- `sftpHost` - SFTP server hostname
-- `sftpPort` - SFTP server port (default: 22)
-- `sftpRemotePath` - Remote directory path for uploads
-
-**Connection (for SFTP):**
-- `sftp_export_server` - Basic Auth connection containing username/password
-
----
-
-## Security Best Practices
-
-**Webhook Signature Validation:**
-- ✅ Always validate `fluent-signature` or `flex.signature` headers
-- ✅ Use `strictValidation: true` in WebhookValidationService
-- ✅ Store public keys in activation variables (not hardcoded)
-- ✅ Use environment-specific keys (dev/staging/prod)
-
-**Credential Management:**
-- ✅ Store SFTP credentials in Versori connection vault (not activation variables)
-- ✅ Use `sftp_export_server` connection with Basic Auth
-- ✅ Rotate credentials quarterly
-- ✅ Use least-privilege accounts
-- ❌ Never store passwords in activation variables
-- ❌ Never log passwords or full signatures
-
----
-
-## Development Workflow
-
-### 1. Choose Template
-
-Select the template that matches your entity type and use case:
-- **FULFILMENT + SFTP** → Use fulfilment export template
-- **ORDER + Attributes** → Use order update template
-
-### 2. Configure Versori
-
-1. Create new project in Versori workspace
-2. Configure Fluent Commerce connection (OAuth2)
-3. Set activation variables (public key + SFTP if needed)
-
-### 3. Deploy Template
-
-1. Copy template code to your project
-2. Customize business logic in services/
-3. Test with Versori dev environment
-4. Deploy to production
-
-### 4. Configure Rubix Workflow
-
-1. Create/edit Rubix workflow in Fluent Commerce
-2. Add SendWebhook action
-3. Set URL to your Versori endpoint
-4. Build Event payload with required fields
-5. Test webhook triggers from Rubix
-
----
-
-## Testing
-
-### Test Webhook Signature Validation
-
-```bash
-# Test with invalid signature (should fail)
-curl -X POST https://workspace.versori.run/rubix-fulfilment \
-  -H "Content-Type: application/json" \
-  -H "fluent-signature: invalid" \
-  -d '{"entityType":"FULFILMENT","entityRef":"FF-001","retailerId":"1"}'
-
-# Expected: { success: false, error: "Invalid webhook signature" }
-```
-
-### Test with Valid Payload
-
-```bash
-# Test with valid payload (signature validation only in real scenario)
-curl -X POST https://workspace.versori.run/rubix-fulfilment \
-  -H "Content-Type: application/json" \
-  -d '{
-    "entityType": "FULFILMENT",
-    "entityRef": "FF-001",
-    "retailerId": "1",
-    "id": "evt-123"
-  }'
-```
-
----
-
-## Troubleshooting
-
-### Common Issues
-
-**Issue: "Invalid webhook signature"**
-- **Cause**: Wrong public key or payload modified
-- **Solution**: Verify `fluentPublicKey` matches Fluent environment (dev/staging/prod)
-
-**Issue: "Missing retailerId in payload"**
-- **Cause**: Rubix Event payload incomplete
-- **Solution**: Add `retailerId` field in Rubix Event payload builder
-
-**Issue: "SFTP upload failed" (Fulfilment template)**
-- **Cause**: Invalid SFTP credentials or connectivity
-- **Solution**: Test SFTP manually, verify host/port/credentials
-
-**Issue: "GraphQL mutation failed" (Order template)**
-- **Cause**: Invalid permissions or syntax
-- **Solution**: Verify user has UPDATE_ORDER permission, check mutation syntax
-
----
-
-## Mapping Pattern Comparison
-
-### Overview
-
-The Fulfilment → SFTP XML template offers **two mapping patterns** for transforming GraphQL data to XML:
-
-1. **[Inline Mapping Pattern](./template-webhook-rubix-fulfilment-to-sftp-xml-inline.md)** 🔵 - Manual object construction
-2. **[UniversalMapper Pattern](./template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md)** 🟢 - External JSON mapping + custom resolvers
-
-### Quick Comparison
-
-| Aspect | Inline Pattern 🔵 | UniversalMapper Pattern 🟢 |
-|--------|-------------------|---------------------------|
-| **Complexity** | Simpler | More complex |
-| **Config Files** | None | External JSON config |
-| **Resolvers** | None | SDK + custom resolvers |
-| **Best For** | Simple webhooks, tightly-coupled schemas | Reusable configs, multi-environment |
-| **Code Location** | All in one file | Separated (config/, resolvers/, services/) |
-| **Field Updates** | Require code changes | Change JSON config only |
-| **Testing** | Inline test logic | Config + resolvers separately testable |
-| **Reusability** | Limited | High |
-| **Debugging** | Faster (all visible) | Slower (multiple files) |
-
-### Pattern 1: Inline Mapping 🔵
-
-**File:** [`template-webhook-rubix-fulfilment-to-sftp-xml-inline.md`](./template-webhook-rubix-fulfilment-to-sftp-xml-inline.md)
-
-**When to Use:**
-- ✅ Simple webhook handlers
-- ✅ Tightly-coupled 3PL XML schemas
-- ✅ Fast debugging needs
-- ✅ Single-purpose transformations
-- ✅ Small teams / rapid prototyping
-
-**Code Example:**
-```typescript
-// src/services/xml-export.service.ts
-// NO external config, NO resolvers, NO mapping files
-const xmlData = {
-  Fulfilment: {
-    '@ref': fulfilmentData.ref,
-    '@status': fulfilmentData.status,
-    OrderRef: fulfilmentData.order?.ref || '',
-    Customer: fulfilmentData.order?.customer ? {
-      FirstName: fulfilmentData.order.customer.firstName || '',
-      LastName: fulfilmentData.order.customer.lastName || '',
-    } : {},
-    Items: {
-      Item: fulfilmentData.items?.edges?.map(edge => ({
-        '@ref': edge.node.ref,
-        ProductRef: edge.node.orderItem?.productRef || '',
-        Quantity: edge.node.quantity,
-      })) || [],
-    },
-  },
-};
-
-const xmlString = xmlBuilder.build(xmlData, 'FulfilmentExport');
-```
-
-**Project Structure:**
-```
-rubix-fulfilment-export/
-├── package.json
-├── index.ts
-└── src/
-    ├── workflows/webhook/
-    ├── services/              # Inline mapping in xml-export.service.ts
-    └── types/
-```
-
-**Pros:**
-- ✅ Simpler to understand - all logic in one place
-- ✅ Faster debugging - no jumping between files
-- ✅ Fewer files to maintain
-- ✅ No external dependencies on mapping config
-
-**Cons:**
-- ❌ Field changes require code modifications
-- ❌ Harder to reuse across projects
-- ❌ No SDK resolver benefits
-- ❌ Less testable (logic embedded in service)
-
----
-
-### Pattern 2: UniversalMapper 🟢
-
-**File:** [`template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md`](./template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md)
-
-**When to Use:**
-- ✅ Reusable configs across projects
-- ✅ Multi-environment deployments (dev/staging/prod)
-- ✅ Complex transformation logic
-- ✅ SDK resolver benefits (parseInt, formatDate, uppercase, etc.)
-- ✅ Frequent field mapping changes
-- ✅ Large teams / production systems
-
-**Code Example:**
-```typescript
-// config/fulfilment-xml-mapping.json
-{
-  "fields": {
-    "@ref": { "source": "ref", "required": true },
-    "@status": { "source": "status", "resolver": "sdk.uppercase" },
-    "OrderRef": { "source": "order.ref", "default": "" },
-    "Customer": {
-      "type": "object",
-      "fields": {
-        "FirstName": { "source": "order.customer.firstName", "default": "" }
-      }
-    }
-  }
-}
-
-// src/services/xml-export.service.ts
-import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-import mappingConfig from '../config/fulfilment-xml-mapping.json' with { type: 'json' };
-import { customResolvers } from '../resolvers/fulfilment-resolvers';
-
-const mapper = new UniversalMapper(mappingConfig, { customResolvers });
-const mappingResult = await mapper.map(fulfilmentData);
-const xmlString = xmlBuilder.build(mappingResult.data, 'FulfilmentExport');
-```
-
-**Project Structure:**
-```
-rubix-fulfilment-export/
-├── package.json
-├── index.ts
-├── config/
-│   └── fulfilment-xml-mapping.json    # ✨ External mapping config
-└── src/
-    ├── workflows/webhook/
-    ├── services/                       # Uses UniversalMapper
-    ├── resolvers/                      # ✨ Custom transformations
-    │   └── fulfilment-resolvers.ts
-    └── types/
-```
-
-**Pros:**
-- ✅ Reusable mapping configuration across projects
-- ✅ Environment-specific configs (dev/staging/prod)
-- ✅ SDK resolvers built-in (parseInt, formatDate, uppercase, etc.)
-- ✅ Custom resolvers for complex logic
-- ✅ Field changes don't require code changes
-- ✅ Mapping config is unit testable
-
-**Cons:**
-- ❌ More complex to set up
-- ❌ More files to maintain (config/, resolvers/)
-- ❌ Slower debugging (jumping between files)
-- ❌ Overhead for simple transformations
-
----
-
-### Decision Tree
-
-```
-Need to transform GraphQL data to XML for 3PL webhook?
-│
-├─ Is this a simple, one-off webhook?
-│  └─ YES → Use Inline Pattern 🔵
-│
-├─ Will the mapping config be reused across projects?
-│  └─ YES → Use UniversalMapper Pattern 🟢
-│
-├─ Do you need environment-specific configs (dev/staging/prod)?
-│  └─ YES → Use UniversalMapper Pattern 🟢
-│
-├─ Will field mappings change frequently?
-│  └─ YES → Use UniversalMapper Pattern 🟢
-│
-├─ Do you need SDK resolvers (parseInt, formatDate, etc.)?
-│  └─ YES → Use UniversalMapper Pattern 🟢
-│
-└─ DEFAULT: For production systems → Use UniversalMapper Pattern 🟢
-```
-
----
-
-## Related Documentation
-
-- [Webhook Validation Guide](../../../../02-CORE-GUIDES/webhook-validation/) - Signature validation details
-- [Versori Platform Guide](../../../../04-REFERENCE/platforms/versori/) - Platform documentation
-- [GraphQL Operations Guide](../../../../02-CORE-GUIDES/graphql/) - Query and mutation patterns
-- [SFTP Data Sources Guide](../../../../02-CORE-GUIDES/data-sources/) - SFTP configuration
-- [Payment Gateway Integration](../../../webhooks/template-webhook-payment-gateway-integration.md) - Similar webhook pattern
-
----
-
-## Version History
-
-### v2.0.0 (2025-01-25)
-- ✅ Split generic template into two entity-specific templates
-- ✅ Fulfilment template: GraphQL queries + XML generation + SFTP upload
-- ✅ Order template: GraphQL mutations + attribute updates
-- ✅ Applied critical fixes: retailerId validation, SFTP options parameter
-- ✅ Added SDK error type handling (GraphQLError, AuthenticationError, DataSourceError)
-- ✅ Improved type safety (replaced `any` with proper SDK types)
-- ✅ Comprehensive testing, troubleshooting, and monitoring sections
-
-### v1.0.0 (2025-01-XX)
-- Initial generic Rubix webhook template (deprecated - use v2.0.0 specific templates)
-
----
-
-**Next Steps**: Choose the template that matches your use case, copy the code, configure activation variables, and deploy to Versori!
+# Rubix Webhook Templates
+
+> **Templates for receiving webhooks from Fluent Commerce Rubix workflows**
+> Complete pattern: Rubix → Versori → Validate → Query/Mutate → Logic → Output
+
+## Overview
+
+This directory contains templates demonstrating how to receive webhooks from Fluent Commerce Rubix workflows, validate signatures, and perform entity-specific operations (GraphQL queries, mutations, SFTP exports).
+
+## Pattern Flow
+
+```
+┌─────────────────┐
+│ Rubix Workflow  │
+│ (Fluent Commerce)│
+└────────┬─────────┘
+         │
+         │ HTTP POST with signature
+         │ Payload: { entityRef, entityType, retailerId }
+         ▼
+┌─────────────────────────────────────┐
+│ Versori Webhook Endpoint            │
+│ 1. Validate signature (sync)        │
+│ 2. Extract entity ref               │
+│ 3. Return HTTP 200 OK immediately   │
+│                                     │
+│ Background (fire-and-forget):       │
+│ 4. Query/mutate Fluent via GraphQL  │
+│ 5. Perform business logic           │
+│ 6. Export to SFTP (if applicable)   │
+└─────────────────────────────────────┘
+```
+
+## Available Templates
+
+| Template | Entity | Destination | Complexity | Status | Use Case |
+|----------|--------|-------------|------------|--------|----------|
+| **[Fulfilment → SFTP XML (Inline)](./template-webhook-rubix-fulfilment-to-sftp-xml-inline.md)** | FULFILMENT | SFTP + XML | Medium | ✅ Production Ready | Export fulfilment details to 3PL/WMS partner via SFTP when fulfilment is created/updated (inline mapping) |
+| **[Fulfilment → SFTP XML (UniversalMapper)](./template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md)** | FULFILMENT | SFTP + XML | Medium | ✅ Production Ready | Export fulfilment details to 3PL/WMS partner via SFTP when fulfilment is created/updated (external JSON mapping) |
+| **[Order → Attribute Update](./template-webhook-rubix-order-attribute-update.md)** | ORDER | GraphQL | Simple | ✅ Production Ready | Update order attributes when order status changes in Rubix workflow |
+
+## Template Selection Guide
+
+### When to Use Fulfilment → SFTP XML
+
+✅ **Use this template if:**
+- Receiving FULFILMENT webhooks from Rubix workflows
+- Need to export fulfilment details to external systems
+- 3PL/WMS requires XML format via SFTP
+- Need fulfilment + line items + order + address details
+- Require warehouse management system integration
+
+**What it does:**
+1. Validates webhook signature (fast, ~50ms response)
+2. Background: Queries fulfilment details via GraphQL
+3. Generates XML with XMLBuilder (automatic escaping)
+4. Uploads to 3PL SFTP server
+5. Always cleans up SFTP connections
+
+**Key Features:**
+- GraphQL queries (fulfilment + nested fields)
+- XML generation with safe escaping
+- SFTP upload with connection pooling
+- Comprehensive error handling (GraphQL, SFTP errors)
+
+**Two Mapping Patterns Available:**
+
+The Fulfilment → SFTP XML template comes in **two versions** - choose based on your needs:
+
+| Pattern | File | Best For |
+|---------|------|----------|
+| **🔵 Inline Mapping** | [template-webhook-rubix-fulfilment-to-sftp-xml-inline.md](./template-webhook-rubix-fulfilment-to-sftp-xml-inline.md) | Simple webhooks, fast debugging, tightly-coupled schemas |
+| **🟢 UniversalMapper** | [template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md](./template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md) | Reusable configs, multi-environment, complex transformations |
+
+**Quick Decision Guide:**
+- **Use Inline** if: Simple XML structure (<20 fields), rarely changes, single environment, rapid prototyping
+- **Use UniversalMapper** if: Complex XML (>20 fields), frequent changes, multi-environment (dev/staging/prod), need SDK resolvers
+
+See [Mapping Pattern Comparison](#mapping-pattern-comparison) below for detailed comparison.
+
+---
+
+### When to Use Order → Attribute Update
+
+✅ **Use this template if:**
+- Receiving ORDER webhooks from Rubix workflows
+- Need to update order custom attributes
+- Simple attribute updates without external systems
+- No SFTP/S3 export required
+
+**What it does:**
+1. Validates webhook signature (fast, ~50ms response)
+2. Background: Updates order attributes via GraphQL mutation
+3. Records processing timestamp
+4. No external system integration
+
+**Key Features:**
+- GraphQL mutations (attribute updates)
+- Lightweight (no SFTP/XML complexity)
+- Fast background processing (~300-500ms)
+- Simplified error handling
+
+---
+
+## Key Concepts
+
+### Rubix Workflow Configuration
+
+Rubix workflows in Fluent Commerce can call external webhook endpoints. When configuring a Rubix workflow:
+
+1. **Add SendWebhook Action** - Configure to call Versori webhook endpoint
+2. **Set Webhook URL** - Your Versori endpoint URL:
+   - Fulfilment: `https://{workspace}.versori.run/rubix-fulfilment`
+   - Order: `https://{workspace}.versori.run/rubix-order`
+3. **Build Event Payload** - Include:
+   - `entityRef` - Entity reference (required)
+   - `entityType` - "FULFILMENT" or "ORDER" (required)
+   - `retailerId` - Retailer ID (required for GraphQL)
+   - Additional context fields as needed
+4. **Signature Headers** - Automatically included by Fluent Commerce (`fluent-signature`, `flex.signature`)
+
+### Versori Webhook Handler
+
+Both templates follow the same core pattern:
+- **Validates webhook signature** using `WebhookValidationService` (synchronously, ~10-50ms)
+- **Returns fast response** using `mode: 'sync'` + fire-and-forget pattern (~50ms)
+- **Processes in background** without blocking response (GraphQL, SFTP, etc.)
+- **Validates retailerId** before `setRetailerId()` to prevent 401 errors
+- **Handles SDK errors** (GraphQLError, AuthenticationError, DataSourceError)
+
+**Critical Pattern:**
+- ✅ Webhook handler uses `response: { mode: 'sync' }` directly (no `.then(http())`)
+- ✅ Signature validation happens synchronously in webhook handler
+- ✅ Background processing uses fire-and-forget (no `await` on background promise)
+- ❌ **DO NOT** use `.then(http())` pattern - it creates unnecessary chaining
+
+### Differences Between Templates
+
+| Aspect | Fulfilment → SFTP XML | Order → Attribute Update |
+|--------|------------------------|--------------------------|
+| **Entity Type** | FULFILMENT | ORDER |
+| **GraphQL Operation** | Query (fetch details) | Mutation (update attributes) |
+| **Data Transformation** | ✅ XML generation | ❌ None |
+| **External System** | ✅ SFTP upload | ❌ None |
+| **SFTP Cleanup** | ✅ dispose() required | ❌ N/A |
+| **Complexity** | Medium (query + XML + SFTP) | Simple (mutation only) |
+| **Background Time** | ~2-5s | ~300-500ms |
+| **Use Case** | 3PL/WMS integration | Order tracking |
+
+---
+
+## Common Configuration
+
+### Activation Variables (All Templates)
+
+```json
+{
+  "fluentPublicKey": "-----BEGIN PUBLIC KEY-----...-----END PUBLIC KEY-----"
+}
+```
+
+### Additional for Fulfilment → SFTP XML
+
+```json
+{
+  "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 SFTP Credential Management section below).
+
+### Versori Connections (Required for All)
+
+| Connection | Description |
+|------------|-------------|
+| `fluent_commerce` | OAuth2 connection to Fluent Commerce API |
+| `sftp_export_server` | Basic Auth connection for SFTP credentials (username/password) - Required for Fulfilment templates |
+
+## SFTP Credential Management
+
+**For Fulfilment → SFTP XML templates:**
+
+SFTP credentials (username/password) are stored securely in Versori connection vault, not in activation variables.
+
+**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. Code automatically retrieves credentials using `ctx.credentials().getAccessToken('sftp_export_server')`
+
+**Activation Variables (for SFTP):**
+- `sftpHost` - SFTP server hostname
+- `sftpPort` - SFTP server port (default: 22)
+- `sftpRemotePath` - Remote directory path for uploads
+
+**Connection (for SFTP):**
+- `sftp_export_server` - Basic Auth connection containing username/password
+
+---
+
+## Security Best Practices
+
+**Webhook Signature Validation:**
+- ✅ Always validate `fluent-signature` or `flex.signature` headers
+- ✅ Use `strictValidation: true` in WebhookValidationService
+- ✅ Store public keys in activation variables (not hardcoded)
+- ✅ Use environment-specific keys (dev/staging/prod)
+
+**Credential Management:**
+- ✅ Store SFTP credentials in Versori connection vault (not activation variables)
+- ✅ Use `sftp_export_server` connection with Basic Auth
+- ✅ Rotate credentials quarterly
+- ✅ Use least-privilege accounts
+- ❌ Never store passwords in activation variables
+- ❌ Never log passwords or full signatures
+
+---
+
+## Development Workflow
+
+### 1. Choose Template
+
+Select the template that matches your entity type and use case:
+- **FULFILMENT + SFTP** → Use fulfilment export template
+- **ORDER + Attributes** → Use order update template
+
+### 2. Configure Versori
+
+1. Create new project in Versori workspace
+2. Configure Fluent Commerce connection (OAuth2)
+3. Set activation variables (public key + SFTP if needed)
+
+### 3. Deploy Template
+
+1. Copy template code to your project
+2. Customize business logic in services/
+3. Test with Versori dev environment
+4. Deploy to production
+
+### 4. Configure Rubix Workflow
+
+1. Create/edit Rubix workflow in Fluent Commerce
+2. Add SendWebhook action
+3. Set URL to your Versori endpoint
+4. Build Event payload with required fields
+5. Test webhook triggers from Rubix
+
+---
+
+## Testing
+
+### Test Webhook Signature Validation
+
+```bash
+# Test with invalid signature (should fail)
+curl -X POST https://workspace.versori.run/rubix-fulfilment \
+  -H "Content-Type: application/json" \
+  -H "fluent-signature: invalid" \
+  -d '{"entityType":"FULFILMENT","entityRef":"FF-001","retailerId":"1"}'
+
+# Expected: { success: false, error: "Invalid webhook signature" }
+```
+
+### Test with Valid Payload
+
+```bash
+# Test with valid payload (signature validation only in real scenario)
+curl -X POST https://workspace.versori.run/rubix-fulfilment \
+  -H "Content-Type: application/json" \
+  -d '{
+    "entityType": "FULFILMENT",
+    "entityRef": "FF-001",
+    "retailerId": "1",
+    "id": "evt-123"
+  }'
+```
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue: "Invalid webhook signature"**
+- **Cause**: Wrong public key or payload modified
+- **Solution**: Verify `fluentPublicKey` matches Fluent environment (dev/staging/prod)
+
+**Issue: "Missing retailerId in payload"**
+- **Cause**: Rubix Event payload incomplete
+- **Solution**: Add `retailerId` field in Rubix Event payload builder
+
+**Issue: "SFTP upload failed" (Fulfilment template)**
+- **Cause**: Invalid SFTP credentials or connectivity
+- **Solution**: Test SFTP manually, verify host/port/credentials
+
+**Issue: "GraphQL mutation failed" (Order template)**
+- **Cause**: Invalid permissions or syntax
+- **Solution**: Verify user has UPDATE_ORDER permission, check mutation syntax
+
+---
+
+## Mapping Pattern Comparison
+
+### Overview
+
+The Fulfilment → SFTP XML template offers **two mapping patterns** for transforming GraphQL data to XML:
+
+1. **[Inline Mapping Pattern](./template-webhook-rubix-fulfilment-to-sftp-xml-inline.md)** 🔵 - Manual object construction
+2. **[UniversalMapper Pattern](./template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md)** 🟢 - External JSON mapping + custom resolvers
+
+### Quick Comparison
+
+| Aspect | Inline Pattern 🔵 | UniversalMapper Pattern 🟢 |
+|--------|-------------------|---------------------------|
+| **Complexity** | Simpler | More complex |
+| **Config Files** | None | External JSON config |
+| **Resolvers** | None | SDK + custom resolvers |
+| **Best For** | Simple webhooks, tightly-coupled schemas | Reusable configs, multi-environment |
+| **Code Location** | All in one file | Separated (config/, resolvers/, services/) |
+| **Field Updates** | Require code changes | Change JSON config only |
+| **Testing** | Inline test logic | Config + resolvers separately testable |
+| **Reusability** | Limited | High |
+| **Debugging** | Faster (all visible) | Slower (multiple files) |
+
+### Pattern 1: Inline Mapping 🔵
+
+**File:** [`template-webhook-rubix-fulfilment-to-sftp-xml-inline.md`](./template-webhook-rubix-fulfilment-to-sftp-xml-inline.md)
+
+**When to Use:**
+- ✅ Simple webhook handlers
+- ✅ Tightly-coupled 3PL XML schemas
+- ✅ Fast debugging needs
+- ✅ Single-purpose transformations
+- ✅ Small teams / rapid prototyping
+
+**Code Example:**
+```typescript
+// src/services/xml-export.service.ts
+// NO external config, NO resolvers, NO mapping files
+const xmlData = {
+  Fulfilment: {
+    '@ref': fulfilmentData.ref,
+    '@status': fulfilmentData.status,
+    OrderRef: fulfilmentData.order?.ref || '',
+    Customer: fulfilmentData.order?.customer ? {
+      FirstName: fulfilmentData.order.customer.firstName || '',
+      LastName: fulfilmentData.order.customer.lastName || '',
+    } : {},
+    Items: {
+      Item: fulfilmentData.items?.edges?.map(edge => ({
+        '@ref': edge.node.ref,
+        ProductRef: edge.node.orderItem?.productRef || '',
+        Quantity: edge.node.quantity,
+      })) || [],
+    },
+  },
+};
+
+const xmlString = xmlBuilder.build(xmlData, 'FulfilmentExport');
+```
+
+**Project Structure:**
+```
+rubix-fulfilment-export/
+├── package.json
+├── index.ts
+└── src/
+    ├── workflows/webhook/
+    ├── services/              # Inline mapping in xml-export.service.ts
+    └── types/
+```
+
+**Pros:**
+- ✅ Simpler to understand - all logic in one place
+- ✅ Faster debugging - no jumping between files
+- ✅ Fewer files to maintain
+- ✅ No external dependencies on mapping config
+
+**Cons:**
+- ❌ Field changes require code modifications
+- ❌ Harder to reuse across projects
+- ❌ No SDK resolver benefits
+- ❌ Less testable (logic embedded in service)
+
+---
+
+### Pattern 2: UniversalMapper 🟢
+
+**File:** [`template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md`](./template-webhook-rubix-fulfilment-to-sftp-xml-universal-mapper.md)
+
+**When to Use:**
+- ✅ Reusable configs across projects
+- ✅ Multi-environment deployments (dev/staging/prod)
+- ✅ Complex transformation logic
+- ✅ SDK resolver benefits (parseInt, formatDate, uppercase, etc.)
+- ✅ Frequent field mapping changes
+- ✅ Large teams / production systems
+
+**Code Example:**
+```typescript
+// config/fulfilment-xml-mapping.json
+{
+  "fields": {
+    "@ref": { "source": "ref", "required": true },
+    "@status": { "source": "status", "resolver": "sdk.uppercase" },
+    "OrderRef": { "source": "order.ref", "default": "" },
+    "Customer": {
+      "type": "object",
+      "fields": {
+        "FirstName": { "source": "order.customer.firstName", "default": "" }
+      }
+    }
+  }
+}
+
+// src/services/xml-export.service.ts
+import { UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+import mappingConfig from '../config/fulfilment-xml-mapping.json' with { type: 'json' };
+import { customResolvers } from '../resolvers/fulfilment-resolvers';
+
+const mapper = new UniversalMapper(mappingConfig, { customResolvers });
+const mappingResult = await mapper.map(fulfilmentData);
+const xmlString = xmlBuilder.build(mappingResult.data, 'FulfilmentExport');
+```
+
+**Project Structure:**
+```
+rubix-fulfilment-export/
+├── package.json
+├── index.ts
+├── config/
+│   └── fulfilment-xml-mapping.json    # ✨ External mapping config
+└── src/
+    ├── workflows/webhook/
+    ├── services/                       # Uses UniversalMapper
+    ├── resolvers/                      # ✨ Custom transformations
+    │   └── fulfilment-resolvers.ts
+    └── types/
+```
+
+**Pros:**
+- ✅ Reusable mapping configuration across projects
+- ✅ Environment-specific configs (dev/staging/prod)
+- ✅ SDK resolvers built-in (parseInt, formatDate, uppercase, etc.)
+- ✅ Custom resolvers for complex logic
+- ✅ Field changes don't require code changes
+- ✅ Mapping config is unit testable
+
+**Cons:**
+- ❌ More complex to set up
+- ❌ More files to maintain (config/, resolvers/)
+- ❌ Slower debugging (jumping between files)
+- ❌ Overhead for simple transformations
+
+---
+
+### Decision Tree
+
+```
+Need to transform GraphQL data to XML for 3PL webhook?
+│
+├─ Is this a simple, one-off webhook?
+│  └─ YES → Use Inline Pattern 🔵
+│
+├─ Will the mapping config be reused across projects?
+│  └─ YES → Use UniversalMapper Pattern 🟢
+│
+├─ Do you need environment-specific configs (dev/staging/prod)?
+│  └─ YES → Use UniversalMapper Pattern 🟢
+│
+├─ Will field mappings change frequently?
+│  └─ YES → Use UniversalMapper Pattern 🟢
+│
+├─ Do you need SDK resolvers (parseInt, formatDate, etc.)?
+│  └─ YES → Use UniversalMapper Pattern 🟢
+│
+└─ DEFAULT: For production systems → Use UniversalMapper Pattern 🟢
+```
+
+---
+
+## Related Documentation
+
+- [Webhook Validation Guide](../../../../02-CORE-GUIDES/webhook-validation/) - Signature validation details
+- [Versori Platform Guide](../../../../04-REFERENCE/platforms/versori/) - Platform documentation
+- [GraphQL Operations Guide](../../../../02-CORE-GUIDES/graphql/) - Query and mutation patterns
+- [SFTP Data Sources Guide](../../../../02-CORE-GUIDES/data-sources/) - SFTP configuration
+- [Payment Gateway Integration](../../../webhooks/template-webhook-payment-gateway-integration.md) - Similar webhook pattern
+
+---
+
+## Version History
+
+### v2.0.0 (2025-01-25)
+- ✅ Split generic template into two entity-specific templates
+- ✅ Fulfilment template: GraphQL queries + XML generation + SFTP upload
+- ✅ Order template: GraphQL mutations + attribute updates
+- ✅ Applied critical fixes: retailerId validation, SFTP options parameter
+- ✅ Added SDK error type handling (GraphQLError, AuthenticationError, DataSourceError)
+- ✅ Improved type safety (replaced `any` with proper SDK types)
+- ✅ Comprehensive testing, troubleshooting, and monitoring sections
+
+### v1.0.0 (2025-01-XX)
+- Initial generic Rubix webhook template (deprecated - use v2.0.0 specific templates)
+
+---
+
+**Next Steps**: Choose the template that matches your use case, copy the code, configure activation variables, and deploy to Versori!