@fluentcommerce/fc-connect-sdk 0.1.53 → 0.1.55

package/docs/01-TEMPLATES/versori/workflows/ingestion/event-api/template-ingestion-payload-json-order-cancel-event.md

@@ -1,959 +1,959 @@
----
-template_id: tpl-ingest-payload-json-to-order-cancel-event
-canonical_filename: template-ingestion-payload-json-order-cancel-event.md
-sdk_version: latest
-runtime: versori
-direction: ingestion
-source: payload-json
-destination: fluent-event-api
-entity: order
-format: json
-logging: versori
-status: stable
-features:
-  - direct-payload-processing
-  - json-parsing
-  - event-api-integration
-  - error-handling
----
-
-# Template: Ingestion - Payload JSON to Order Cancel Event
-
-**SDK Version:** @fluentcommerce/fc-connect-sdk@latest
-**Last Updated:** 2025-01-24
-**Deployment Target:** Versori Platform
-
----
-
-## 📋 Implementation Prompt
-
-```
-I need a Versori webhook ingestion that:
-
-1) Receives JSON payload directly in webhook request body
-2) Parses JSON to extract order reference
-3) Builds OrderCancel event payload with retailerId, name, entityRef, entityType
-4) Sends event to Fluent Commerce Event API (async)
-5) Returns success/error response
-6) Uses native Versori log from context
-
-Use the loaded docs to fill in SDK specifics and best practices.
-Keep the structure identical to the template; only adapt where needed.
-```
-
----
-
-## 📋 Template Overview
-
-This connector runs on the Versori platform. It receives JSON payloads directly via webhook, extracts the order reference, and sends OrderCancel events to Fluent Commerce Event API. Most operational settings (Fluent account/connection) are configured via activation variables.
-
-### What This Template Does
-
-```
-┌────────────────────────────────────────────────────────────────┐
-│          INGESTION WORKFLOW              │
-└────────────────────────────────────────────────────────────────┘
-
-1. TRIGGER
-  └─ Webhook: HTTP POST endpoint receives JSON payload
-
-2. RECEIVE PAYLOAD
-  ├─ Extract JSON from request body (ctx.data or ctx.request)
-  ├─ Validate payload structure
-  └─ Log incoming request
-
-3. PARSE JSON
-  ├─ Parse JSON payload (if raw string)
-  ├─ Extract order reference field
-  └─ Validate required fields
-
-4. BUILD EVENT
-  ├─ Construct OrderCancel event payload
-  ├─ Set retailerId (from config or payload)
-  ├─ Set name: "OrderCancel"
-  ├─ Set entityRef: order reference
-  └─ Set entityType: "ORDER"
-
-5. SEND EVENT (Event API)
-  ├─ Send event to Fluent Commerce Event API (async)
-  ├─ Handle success/error responses
-  └─ Log event result
-
-6. RETURN RESPONSE
-  ├─ Return success with event details
-  └─ Return error with details if failed
-```
-
-### Key Features
-
-- **Direct Payload Processing**: Receives JSON payload directly in webhook request body
-- **JSON Parsing**: Handles both pre-parsed and raw JSON payloads
-- **Event API Integration**: Sends OrderCancel events to Fluent Commerce
-- **Error Handling**: Comprehensive error handling with detailed logging
-- **Native Versori Logging**: Uses Versori log from context
-- **Flexible Order Reference Extraction**: Supports multiple JSON field patterns
-
-### 📦 Package Information
-
-**SDK:** [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk) `latest`
-
-```bash
-npm install @fluentcommerce/fc-connect-sdk@latest
-```
-
----
-
-**Templates are designed for direct deployment; customize via activation variables.**
-
----
-
-## 📦 SDK Imports (Verified - Versori Optimized)
-
-```typescript
-// ✅ VERIFIED IMPORTS - These match actual SDK exports
-import { Buffer } from 'node:buffer'; // Required for Versori/Deno runtime
-import {
-  createClient, // Universal client factory
-  JSONParserService, // JSON parsing utility
-} from '@fluentcommerce/fc-connect-sdk';
-
-import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Versori platform imports
-import { webhook, http } from '@versori/run';
-```
-
-**Note:** All imports are from actual SDK exports - this code compiles and runs as-is.
-
-**⚠️ CRITICAL - Buffer Import Required:**
-
-The `Buffer` import from `node:buffer` is **required** for Versori/Deno runtime compatibility:
-- Versori and Deno do NOT have `Buffer` as a global (unlike Node.js)
-- Without this import, code will crash with `ReferenceError: Buffer is not defined`
-- Always include this import in Versori templates, even if not directly used in the template code
-- Required for SDK internal operations and any Buffer usage in your code
-
-**✅ VERSORI PLATFORM - Use Native Logs:**
-
-- Use `log` from context: `const { log } = ctx;`
-- Native Versori logs are simpler and automatically integrated with platform monitoring
-
----
-
-## 🔐 Fluent Commerce Connection Setup
-
-**✅ BEST PRACTICE:** Store Fluent Commerce credentials in a Versori connection object:
-
-**Connection Configuration:**
-
-1. **Create Connection in Versori:**
-   - Name: `fluent_commerce`
-   - Type: HTTP Basic Auth or OAuth2
-   - Credentials: Fluent Commerce API credentials
-
-2. **Connection Variables:**
-   - `FLUENT_BASE_URL` - Fluent Commerce API base URL (e.g., `https://api.fluentcommerce.com`)
-   - `FLUENT_RETAILER_ID` - Your retailer ID
-   - `FLUENT_CLIENT_ID` - OAuth client ID (if using OAuth2)
-   - `FLUENT_CLIENT_SECRET` - OAuth client secret (if using OAuth2)
-
-**Benefits:**
-- ✅ Credentials stored securely in Versori vault
-- ✅ Connection can be reused across workflows
-- ✅ No sensitive data in activation variables
-- ✅ Easier credential rotation
-
----
-
-## 📄 Expected JSON Payload Format
-
-The webhook accepts JSON payloads with order reference information. Multiple formats are supported:
-
-### Format 1: Simple Order Reference
-
-```json
-{
-  "orderRef": "ORD-12345"
-}
-```
-
-### Format 2: Nested Order Reference
-
-```json
-{
-  "order": {
-    "reference": "ORD-12345"
-  }
-}
-```
-
-### Format 3: With Additional Metadata
-
-```json
-{
-  "orderRef": "ORD-12345",
-  "reason": "Customer requested cancellation",
-  "cancelledBy": "admin@example.com"
-}
-```
-
-**Note:** The template extracts `orderRef` from the payload. Customize the extraction logic in the service if your payload uses different field names.
-
----
-
-## Event Payload Structure
-
-The template builds and sends this event structure:
-
-```json
-{
-  "retailerId": "{{retailer_id}}",
-  "name": "OrderCancel",
-  "entityRef": "{{order_ref}}",
-  "entityType": "ORDER"
-}
-```
-
-**Fields:**
-- `retailerId`: Retrieved from Fluent Commerce connection or activation variable
-- `name`: Fixed as "OrderCancel"
-- `entityRef`: Extracted from incoming JSON payload
-- `entityType`: Fixed as "ORDER"
-
----
-
-## 🔧 Complete Production Code
-
-### Versori Workflows Structure
-
-**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
-
-**Trigger Types:**
-- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
-
-**Execution Steps (chained to triggers):**
-- **`http()`** → External API calls (chained from webhook)
-
-### Recommended Project Structure
-
-```
-order-cancel-webhook/
-├── index.ts                              # Entry point - exports all workflows
-└── src/
-    ├── workflows/
-    │   └── webhook/
-    │       └── order-cancel.ts           # Webhook: Order cancel handler
-    │
-    ├── services/
-    │   └── order-cancel.service.ts       # Shared orchestration logic
-    │
-    └── types/
-        └── order-cancel.types.ts         # Type definitions
-```
-
-**Benefits:**
-- ✅ Clear structure (webhook handlers in `webhook/`)
-- ✅ Descriptive file names (easy to browse and understand)
-- ✅ Reusable code in `services/` (DRY principle)
-- ✅ Centralized type definitions
-
----
-
-## Workflow Files
-
-### 1. Webhook Workflow (`src/workflows/webhook/order-cancel.ts`)
-
-**Purpose**: Handle order cancel requests via webhook
-**Trigger**: HTTP POST
-**Endpoint**: `POST https://{workspace}.versori.run/order-cancel`
-**Use Cases**: Order cancellation from external systems, manual cancellations
-
-```typescript
-import { webhook, http } from '@versori/run';
-import { executeOrderCancel } from '../../services/order-cancel.service';
-
-/**
- * Webhook: Order Cancel Handler
- *
- * Endpoint: POST https://{workspace}.versori.run/order-cancel
- * Request body: { "orderRef": "ORD-12345" }
- *
- * Pattern: webhook().then(http()) - needs Fluent API access
- * Uses shared service: order-cancel.service.ts
- *
- * SECURITY: Authentication handled via connection parameter
- * No manual API key validation needed - Versori manages this via connection auth
- */
-export const orderCancelWebhook = webhook('order-cancel', {
-  // ✅ Webhook response mode: 'sync'
-  //    - HTTP response sent when handler completes
-  //    - Returns event ID and success status immediately after Fluent accepts event
-  //    - Alternative: 'async' mode would return immediately (before processing)
-  response: { mode: 'sync' },
-  connection: 'order-cancel-webhook', // Versori validates API key
-}).then(
-  http('process-order-cancel', { connection: 'fluent_commerce' }, async ctx => {
-    const { log, data } = ctx;
-
-    log.info('🚀 [WEBHOOK] Order cancel request received', {
-      timestamp: new Date().toISOString(),
-      hasPayload: !!data,
-    });
-
-    try {
-      // Reuse shared orchestration logic
-      const result = await executeOrderCancel(ctx);
-
-      log.info('✅ [WEBHOOK] Order cancel completed successfully', {
-        orderRef: result.orderRef,
-        eventId: result.eventId,
-      });
-
-      return {
-        success: true,
-        orderRef: result.orderRef,
-        eventId: result.eventId,
-        message: 'Order cancel event sent successfully',
-      };
-    } catch (e: any) {
-      log.error('❌ [WEBHOOK] Order cancel failed', {
-        message: e?.message,
-        stack: e?.stack,
-      });
-
-      return {
-        success: false,
-        error: e?.message || 'Unknown error occurred',
-      };
-    }
-  })
-);
-```
-
----
-
-### 2. Entry Point (`index.ts`)
-
-**Purpose**: Register all workflows with Versori platform
-
-```typescript
-/**
- * Entry Point - Registers all workflows with Versori platform
- *
- * Versori automatically discovers and registers exported workflows
- *
- * File Structure:
- * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
- * - src/services/            → Shared service logic (reusable across workflows)
- */
-
-// Import webhook workflows
-import { orderCancelWebhook } from './src/workflows/webhook/order-cancel';
-
-// Register all workflows with Versori platform
-export {
-  // Webhooks (HTTP-based triggers)
-  orderCancelWebhook,
-};
-```
-
-**What Gets Exposed:**
-- ✅ `orderCancelWebhook` → `https://{workspace}.versori.run/order-cancel`
-
----
-
-## 3. Type Definitions (`src/types/order-cancel.types.ts`)
-
-```typescript
-/**
- * Type Definitions for Order Cancel Ingestion
- *
- * Centralized type definitions for order cancel workflow
- */
-
-/**
- * Order cancel request payload
- */
-export interface OrderCancelPayload {
-  orderRef?: string;
-  order?: {
-    reference?: string;
-    ref?: string;
-  };
-  [key: string]: unknown; // Allow additional fields
-}
-
-/**
- * Order cancel event payload
- */
-export interface OrderCancelEvent {
-  retailerId: string;
-  name: 'OrderCancel';
-  entityRef: string;
-  entityType: 'ORDER';
-}
-
-/**
- * Order cancel result
- */
-export interface OrderCancelResult {
-  success: boolean;
-  orderRef: string;
-  eventId?: string;
-  error?: string;
-}
-
-/**
- * Versori Context Interface
- * Represents the Versori runtime context passed to workflow functions
- */
-export interface VersoriContext {
-  log: {
-    info: (message: string, data?: Record<string, unknown>) => void;
-    warn: (message: string, data?: Record<string, unknown>) => void;
-    error: (message: string, data?: Record<string, unknown>) => void;
-    debug?: (message: string, data?: Record<string, unknown>) => void;
-  };
-  data?: unknown;
-  request?: Request;
-  activation: {
-    getVariable: (name: string) => string | undefined;
-    connections?: Record<string, unknown>;
-  };
-  connections?: Record<string, unknown>;
-}
-```
-
----
-
-## 4. Service: Order Cancel Processor (`src/services/order-cancel.service.ts`)
-
-```typescript
-/**
- * Order Cancel Service
- *
- * Processes order cancel requests: extracts order reference from JSON payload,
- * builds OrderCancel event, and sends to Fluent Commerce Event API.
- */
-
-import {
-  createClient,
-  JSONParserService,
-} from '@fluentcommerce/fc-connect-sdk';
-import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
-import type {
-  OrderCancelPayload,
-  OrderCancelResult,
-  VersoriContext,
-} from '../types/order-cancel.types';
-
-/**
- * Extract order reference from JSON payload
- *
- * Supports multiple payload formats:
- * - { orderRef: "ORD-12345" }
- * - { order: { reference: "ORD-12345" } }
- * - { order: { ref: "ORD-12345" } }
- */
-function extractOrderRef(payload: OrderCancelPayload): string | null {
-  // Try direct orderRef field
-  if (payload.orderRef && typeof payload.orderRef === 'string') {
-    return payload.orderRef;
-  }
-
-  // Try nested order.reference
-  if (
-    payload.order &&
-    typeof payload.order === 'object' &&
-    'reference' in payload.order
-  ) {
-    const ref = payload.order.reference;
-    if (typeof ref === 'string') {
-      return ref;
-    }
-  }
-
-  // Try nested order.ref
-  if (
-    payload.order &&
-    typeof payload.order === 'object' &&
-    'ref' in payload.order
-  ) {
-    const ref = payload.order.ref;
-    if (typeof ref === 'string') {
-      return ref;
-    }
-  }
-
-  return null;
-}
-
-/**
- * Parse webhook payload from Versori context
- *
- * Handles both pre-parsed JSON (ctx.data) and raw request body (ctx.request)
- */
-async function parseWebhookPayload(
-  ctx: VersoriContext
-): Promise<OrderCancelPayload | null> {
-  const { log, data, request } = ctx;
-
-  // Scenario 1: Pre-parsed JSON (Versori auto-parsed)
-  if (data && typeof data === 'object') {
-    log.info('📥 [PARSE] Using pre-parsed JSON payload', {
-      hasData: true,
-      dataKeys: Object.keys(data),
-    });
-    return data as OrderCancelPayload;
-  }
-
-  // Scenario 2: Raw request body (need to parse)
-  if (request && typeof request.text === 'function') {
-    log.info('📥 [PARSE] Extracting raw request body');
-    try {
-      const rawBody = await request.text();
-      if (!rawBody || rawBody.trim() === '') {
-        log.error('❌ [PARSE] Request body is empty');
-        return null;
-      }
-
-      const parser = new JSONParserService(log);
-      const parsed = await parser.parse(rawBody);
-      
-      log.info('📥 [PARSE] Successfully parsed JSON payload', {
-        parsedKeys: Object.keys(parsed),
-      });
-      
-      return parsed as OrderCancelPayload;
-    } catch (parseError: unknown) {
-      const errorMessage =
-        parseError instanceof Error ? parseError.message : String(parseError);
-      log.error('❌ [PARSE] Failed to parse JSON payload', {
-        error: errorMessage,
-      });
-      return null;
-    }
-  }
-
-  log.error('❌ [PARSE] No valid payload found in context');
-  return null;
-}
-
-/**
- * Build OrderCancel event payload
- */
-function buildOrderCancelEvent(
-  orderRef: string,
-  retailerId: string
-): {
-  retailerId: string;
-  name: 'OrderCancel';
-  entityRef: string;
-  entityType: 'ORDER';
-} {
-  return {
-    retailerId,
-    name: 'OrderCancel',
-    entityRef: orderRef,
-    entityType: 'ORDER',
-  };
-}
-
-/**
- * Execute order cancel workflow
- *
- * Main orchestration function:
- * 1. Parse webhook payload
- * 2. Extract order reference
- * 3. Create Fluent client
- * 4. Build event payload
- * 5. Send event to Fluent Commerce
- */
-export async function executeOrderCancel(
-  ctx: VersoriContext
-): Promise<OrderCancelResult> {
-  const { log, activation } = ctx;
-
-  log.info('🚀 [SERVICE] Starting order cancel processing');
-
-  // STEP 1: Parse webhook payload
-  const payload = await parseWebhookPayload(ctx);
-  if (!payload) {
-    log.error('❌ [SERVICE] Failed to parse webhook payload', {
-      hasData: !!ctx.data,
-      hasRequest: !!ctx.request,
-    });
-    throw new Error('Failed to parse webhook payload. Ensure Content-Type: application/json is set in request headers.');
-  }
-
-  log.info('📥 [SERVICE] Payload parsed successfully', {
-    payloadKeys: Object.keys(payload),
-  });
-
-  // STEP 2: Extract order reference
-  const orderRef = extractOrderRef(payload);
-  if (!orderRef) {
-    log.error('❌ [SERVICE] Order reference not found in payload', {
-      payloadKeys: Object.keys(payload),
-      expectedFields: ['orderRef', 'order.reference', 'order.ref'],
-    });
-    throw new Error(
-      'Order reference not found in payload. Expected field: orderRef, order.reference, or order.ref'
-    );
-  }
-
-  log.info('✅ [SERVICE] Order reference extracted', { orderRef });
-
-  // STEP 3: Get retailer ID from activation variable or connection
-  const retailerId =
-    activation.getVariable('FLUENT_RETAILER_ID') ||
-    (activation.connections?.fluent_commerce as any)?.retailerId;
-
-  if (!retailerId) {
-    log.error('❌ [SERVICE] Retailer ID not found', {
-      checkedVariables: ['FLUENT_RETAILER_ID'],
-      hasConnection: !!activation.connections?.fluent_commerce,
-    });
-    throw new Error(
-      'Retailer ID not found. Set FLUENT_RETAILER_ID activation variable or configure in connection.'
-    );
-  }
-
-  log.info('✅ [SERVICE] Retailer ID retrieved', { retailerId });
-
-  // STEP 4: Create Fluent client
-  // ✅ Pass ctx directly - createClient auto-detects Versori context
-  const client = await createClient(ctx);
-
-  log.info('✅ [SERVICE] Fluent client created');
-
-  // STEP 5: Build event payload
-  const eventPayload = buildOrderCancelEvent(orderRef, retailerId);
-
-  log.info('📤 [SERVICE] Sending OrderCancel event', {
-    orderRef,
-    retailerId,
-  });
-
-  // STEP 6: Send event to Fluent Commerce
-  // ✅ Using 'async' mode (recommended):
-  //    - Fluent accepts event immediately and processes in background
-  //    - Returns event ID quickly (non-blocking)
-  //    - Better performance for webhook responses
-  //    - Alternative: 'sync' mode waits for event processing (slower, blocking)
-  //      - Sync mode success: { eventId: "...", eventStatus: "COMPLETE" }
-  //      - Sync mode failure: { eventStatus: "FAILED" }
-  //      - Sync mode no match: { eventId: "...", eventStatus: "NO_MATCH" }
-  const response = await client.sendEvent(eventPayload, 'async');
-
-  // Extract event ID from Fluent response
-  // Async mode response format: { id: "evt_abc123", ... }
-  // Sync mode response format (success): { eventId: "...", eventStatus: "COMPLETE" }
-  // Sync mode response format (failure): { eventStatus: "FAILED" }
-  // Sync mode response format (no match): { eventId: "...", eventStatus: "NO_MATCH" }
-  let eventId: string | undefined;
-  
-  if (response && typeof response === 'object') {
-    // Extract event ID first (needed for error messages)
-    if ('id' in response) {
-      eventId = response.id as string;
-    } else if ('eventId' in response) {
-      eventId = response.eventId as string;
-    }
-    
-    // Check for sync mode failure statuses
-    if ('eventStatus' in response) {
-      const eventStatus = response.eventStatus as string;
-      
-      if (eventStatus === 'FAILED') {
-        log.error('❌ [SERVICE] OrderCancel event failed (sync mode)', {
-          orderRef,
-          eventId,
-          eventStatus,
-          response,
-        });
-        throw new Error('Order cancel event failed. Event status: FAILED');
-      }
-      
-      if (eventStatus === 'NO_MATCH') {
-        log.error('❌ [SERVICE] OrderCancel event no match (sync mode)', {
-          orderRef,
-          eventId,
-          eventStatus,
-          response,
-        });
-        throw new Error(
-          'Order cancel event did not match any workflow. Possible causes: incorrect event name, status mismatch, or entity not found. Event status: NO_MATCH'
-        );
-      }
-      
-      if (eventStatus === 'COMPLETE') {
-        log.info('✅ [SERVICE] OrderCancel event completed (sync mode)', {
-          orderRef,
-          eventId,
-          eventStatus,
-        });
-      }
-    }
-  }
-
-  log.info('✅ [SERVICE] OrderCancel event sent successfully', {
-    orderRef,
-    eventId,
-  });
-
-  return {
-    success: true,
-    orderRef,
-    eventId,
-  };
-}
-```
-
----
-
-## 5. Configuration
-
-### Activation Variables
-
-Configure these variables in Versori activation settings:
-
-```json
-{
-  "FLUENT_RETAILER_ID": "your-retailer-id"
-}
-```
-
-**Note:** If using Versori connection for Fluent Commerce, retailer ID can also be configured in the connection settings.
-
-### Webhook Connection
-
-Create a Versori connection for webhook authentication:
-
-1. **Connection Name:** `order-cancel-webhook`
-2. **Type:** API Key or Basic Auth
-3. **Purpose:** Authenticate incoming webhook requests
-
-**Example webhook call:**
-
-```bash
-curl -X POST https://{workspace}.versori.run/order-cancel \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: your-api-key" \
-  -d '{
-    "orderRef": "ORD-12345"
-  }'
-```
-
----
-
-## 6. Error Handling
-
-The template includes comprehensive error handling:
-
-### Payload Parsing Errors
-
-- **Empty payload:** Returns error response
-- **Invalid JSON:** Returns error with parse details
-- **Missing order reference:** Returns error with expected field names
-
-### Event Sending Errors
-
-- **Network errors:** Logged and returned in error response
-- **API errors:** Logged with full error details
-- **Validation errors:** Logged with validation message
-
-### Error Response Format
-
-**Webhook Processing Errors:**
-```json
-{
-  "success": false,
-  "error": "Order reference not found in payload. Expected field: orderRef, order.reference, or order.ref"
-}
-```
-
-**Event API Sync Mode Responses:**
-
-**Success (sync mode):**
-```json
-{
-  "eventId": "421d1709-d0af-4d8a-b7b6-75e40c5fc038",
-  "eventStatus": "COMPLETE"
-}
-```
-
-**Failure (sync mode):**
-```json
-{
-  "eventStatus": "FAILED"
-}
-```
-
-**No Match (sync mode):**
-Occurs when event name is incorrect, status mismatch, or entity not found:
-```json
-{
-  "eventId": "9782c552-033c-47c7-89ea-2b0068fbdd0a",
-  "eventStatus": "NO_MATCH"
-}
-```
-
-The webhook will catch failures and return:
-```json
-{
-  "success": false,
-  "error": "Order cancel event failed. Event status: FAILED"
-}
-```
-
-Or for NO_MATCH:
-```json
-{
-  "success": false,
-  "error": "Order cancel event did not match any workflow. Possible causes: incorrect event name, status mismatch, or entity not found. Event status: NO_MATCH"
-}
-```
-
----
-
-## 7. Testing
-
-### Test with cURL
-
-```bash
-# Test order cancel webhook
-curl -X POST https://{workspace}.versori.run/order-cancel \
-  -H "Content-Type: application/json" \
-  -H "X-API-Key: your-api-key" \
-  -d '{
-    "orderRef": "ORD-12345"
-  }'
-```
-
-### Expected Success Response
-
-```json
-{
-  "success": true,
-  "orderRef": "ORD-12345",
-  "eventId": "evt_abc123",
-  "message": "Order cancel event sent successfully"
-}
-```
-
-**Response Details:**
-- `success`: `true` indicates webhook processed successfully
-- `orderRef`: The order reference that was cancelled
-- `eventId`: Fluent Commerce event ID (returned from Event API async endpoint)
-- `message`: Human-readable success message
-
-**Event API Mode: `async` (recommended)**
-- Fluent accepts the event immediately and returns an event ID
-- Event processing happens in the background
-- Webhook response includes the event ID for tracking
-- Response format: `{ id: "evt_abc123" }`
-
-**Alternative: `sync` mode**
-- Fluent processes the event synchronously before responding
-- Slower response time (waits for event processing)
-- Success response: `{ eventId: "...", eventStatus: "COMPLETE" }`
-- Failure response: `{ eventStatus: "FAILED" }`
-- No match response: `{ eventId: "...", eventStatus: "NO_MATCH" }` (incorrect event name, status mismatch, or entity not found)
-- Use only if you need immediate confirmation of event processing
-
-### Expected Error Response
-
-```json
-{
-  "success": false,
-  "error": "Order reference not found in payload"
-}
-```
-
----
-
-## 8. Customization
-
-### Custom Order Reference Field
-
-If your payload uses a different field name, modify `extractOrderRef()` in `order-cancel.service.ts`:
-
-```typescript
-function extractOrderRef(payload: OrderCancelPayload): string | null {
-  // Add your custom field extraction logic
-  if (payload.customOrderId && typeof payload.customOrderId === 'string') {
-    return payload.customOrderId;
-  }
-  // ... existing logic
-}
-```
-
-### Custom Event Name
-
-To use a different event name, modify `buildOrderCancelEvent()`:
-
-```typescript
-function buildOrderCancelEvent(
-  orderRef: string,
-  retailerId: string
-) {
-  return {
-    retailerId,
-    name: 'CustomOrderCancel', // Change event name
-    entityRef: orderRef,
-    entityType: 'ORDER',
-  };
-}
-```
-
-### Additional Event Data
-
-To include additional data in the event:
-
-```typescript
-function buildOrderCancelEvent(
-  orderRef: string,
-  retailerId: string,
-  additionalData?: Record<string, unknown>
-) {
-  return {
-    retailerId,
-    name: 'OrderCancel',
-    entityRef: orderRef,
-    entityType: 'ORDER',
-    data: additionalData, // Add custom data
-  };
-}
-```
-
----
-
-## Summary
-
-✅ **DO:**
-- Use Versori connection for Fluent Commerce credentials
-- Handle both pre-parsed and raw JSON payloads
-- Extract order reference with fallback patterns
-- Log all steps for debugging
-- Return clear error messages
-
-❌ **DON'T:**
-- Hardcode credentials in code
-- Assume payload format without validation
-- Skip error handling
-- Use `sync` mode for Event API (use `async` for better performance and faster webhook responses)
-
----
-
-## Next Steps
-
-1. **Deploy:** Copy code to your Versori project
-2. **Configure:** Set up Fluent Commerce connection and activation variables
-3. **Test:** Test webhook with sample payloads
-4. **Monitor:** Check Versori logs for event processing
-
-For more templates, see:
-- [XML Payload Template](./template-ingestion-payload-xml-order-cancel-event.md)
-- [Other Event API Templates](./event-api-guide.md)
-
+---
+template_id: tpl-ingest-payload-json-to-order-cancel-event
+canonical_filename: template-ingestion-payload-json-order-cancel-event.md
+sdk_version: latest
+runtime: versori
+direction: ingestion
+source: payload-json
+destination: fluent-event-api
+entity: order
+format: json
+logging: versori
+status: stable
+features:
+  - direct-payload-processing
+  - json-parsing
+  - event-api-integration
+  - error-handling
+---
+
+# Template: Ingestion - Payload JSON to Order Cancel Event
+
+**SDK Version:** @fluentcommerce/fc-connect-sdk@latest
+**Last Updated:** 2025-01-24
+**Deployment Target:** Versori Platform
+
+---
+
+## 📋 Implementation Prompt
+
+```
+I need a Versori webhook ingestion that:
+
+1) Receives JSON payload directly in webhook request body
+2) Parses JSON to extract order reference
+3) Builds OrderCancel event payload with retailerId, name, entityRef, entityType
+4) Sends event to Fluent Commerce Event API (async)
+5) Returns success/error response
+6) Uses native Versori log from context
+
+Use the loaded docs to fill in SDK specifics and best practices.
+Keep the structure identical to the template; only adapt where needed.
+```
+
+---
+
+## 📋 Template Overview
+
+This connector runs on the Versori platform. It receives JSON payloads directly via webhook, extracts the order reference, and sends OrderCancel events to Fluent Commerce Event API. Most operational settings (Fluent account/connection) are configured via activation variables.
+
+### What This Template Does
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│          INGESTION WORKFLOW              │
+└────────────────────────────────────────────────────────────────┘
+
+1. TRIGGER
+  └─ Webhook: HTTP POST endpoint receives JSON payload
+
+2. RECEIVE PAYLOAD
+  ├─ Extract JSON from request body (ctx.data or ctx.request)
+  ├─ Validate payload structure
+  └─ Log incoming request
+
+3. PARSE JSON
+  ├─ Parse JSON payload (if raw string)
+  ├─ Extract order reference field
+  └─ Validate required fields
+
+4. BUILD EVENT
+  ├─ Construct OrderCancel event payload
+  ├─ Set retailerId (from config or payload)
+  ├─ Set name: "OrderCancel"
+  ├─ Set entityRef: order reference
+  └─ Set entityType: "ORDER"
+
+5. SEND EVENT (Event API)
+  ├─ Send event to Fluent Commerce Event API (async)
+  ├─ Handle success/error responses
+  └─ Log event result
+
+6. RETURN RESPONSE
+  ├─ Return success with event details
+  └─ Return error with details if failed
+```
+
+### Key Features
+
+- **Direct Payload Processing**: Receives JSON payload directly in webhook request body
+- **JSON Parsing**: Handles both pre-parsed and raw JSON payloads
+- **Event API Integration**: Sends OrderCancel events to Fluent Commerce
+- **Error Handling**: Comprehensive error handling with detailed logging
+- **Native Versori Logging**: Uses Versori log from context
+- **Flexible Order Reference Extraction**: Supports multiple JSON field patterns
+
+### 📦 Package Information
+
+**SDK:** [@fluentcommerce/fc-connect-sdk](https://www.npmjs.com/package/@fluentcommerce/fc-connect-sdk) `latest`
+
+```bash
+npm install @fluentcommerce/fc-connect-sdk@latest
+```
+
+---
+
+**Templates are designed for direct deployment; customize via activation variables.**
+
+---
+
+## 📦 SDK Imports (Verified - Versori Optimized)
+
+```typescript
+// ✅ VERIFIED IMPORTS - These match actual SDK exports
+import { Buffer } from 'node:buffer'; // Required for Versori/Deno runtime
+import {
+  createClient, // Universal client factory
+  JSONParserService, // JSON parsing utility
+} from '@fluentcommerce/fc-connect-sdk';
+
+import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Versori platform imports
+import { webhook, http } from '@versori/run';
+```
+
+**Note:** All imports are from actual SDK exports - this code compiles and runs as-is.
+
+**⚠️ CRITICAL - Buffer Import Required:**
+
+The `Buffer` import from `node:buffer` is **required** for Versori/Deno runtime compatibility:
+- Versori and Deno do NOT have `Buffer` as a global (unlike Node.js)
+- Without this import, code will crash with `ReferenceError: Buffer is not defined`
+- Always include this import in Versori templates, even if not directly used in the template code
+- Required for SDK internal operations and any Buffer usage in your code
+
+**✅ VERSORI PLATFORM - Use Native Logs:**
+
+- Use `log` from context: `const { log } = ctx;`
+- Native Versori logs are simpler and automatically integrated with platform monitoring
+
+---
+
+## 🔐 Fluent Commerce Connection Setup
+
+**✅ BEST PRACTICE:** Store Fluent Commerce credentials in a Versori connection object:
+
+**Connection Configuration:**
+
+1. **Create Connection in Versori:**
+   - Name: `fluent_commerce`
+   - Type: HTTP Basic Auth or OAuth2
+   - Credentials: Fluent Commerce API credentials
+
+2. **Connection Variables:**
+   - `FLUENT_BASE_URL` - Fluent Commerce API base URL (e.g., `https://api.fluentcommerce.com`)
+   - `FLUENT_RETAILER_ID` - Your retailer ID
+   - `FLUENT_CLIENT_ID` - OAuth client ID (if using OAuth2)
+   - `FLUENT_CLIENT_SECRET` - OAuth client secret (if using OAuth2)
+
+**Benefits:**
+- ✅ Credentials stored securely in Versori vault
+- ✅ Connection can be reused across workflows
+- ✅ No sensitive data in activation variables
+- ✅ Easier credential rotation
+
+---
+
+## 📄 Expected JSON Payload Format
+
+The webhook accepts JSON payloads with order reference information. Multiple formats are supported:
+
+### Format 1: Simple Order Reference
+
+```json
+{
+  "orderRef": "ORD-12345"
+}
+```
+
+### Format 2: Nested Order Reference
+
+```json
+{
+  "order": {
+    "reference": "ORD-12345"
+  }
+}
+```
+
+### Format 3: With Additional Metadata
+
+```json
+{
+  "orderRef": "ORD-12345",
+  "reason": "Customer requested cancellation",
+  "cancelledBy": "admin@example.com"
+}
+```
+
+**Note:** The template extracts `orderRef` from the payload. Customize the extraction logic in the service if your payload uses different field names.
+
+---
+
+## Event Payload Structure
+
+The template builds and sends this event structure:
+
+```json
+{
+  "retailerId": "{{retailer_id}}",
+  "name": "OrderCancel",
+  "entityRef": "{{order_ref}}",
+  "entityType": "ORDER"
+}
+```
+
+**Fields:**
+- `retailerId`: Retrieved from Fluent Commerce connection or activation variable
+- `name`: Fixed as "OrderCancel"
+- `entityRef`: Extracted from incoming JSON payload
+- `entityType`: Fixed as "ORDER"
+
+---
+
+## 🔧 Complete Production Code
+
+### Versori Workflows Structure
+
+**Key Concept**: Versori workflows are organized by **trigger type** at the first level, then by **specific workflow** with descriptive file names.
+
+**Trigger Types:**
+- **`webhook()`** → HTTP-based triggers (event-driven) - Creates HTTP endpoints
+
+**Execution Steps (chained to triggers):**
+- **`http()`** → External API calls (chained from webhook)
+
+### Recommended Project Structure
+
+```
+order-cancel-webhook/
+├── index.ts                              # Entry point - exports all workflows
+└── src/
+    ├── workflows/
+    │   └── webhook/
+    │       └── order-cancel.ts           # Webhook: Order cancel handler
+    │
+    ├── services/
+    │   └── order-cancel.service.ts       # Shared orchestration logic
+    │
+    └── types/
+        └── order-cancel.types.ts         # Type definitions
+```
+
+**Benefits:**
+- ✅ Clear structure (webhook handlers in `webhook/`)
+- ✅ Descriptive file names (easy to browse and understand)
+- ✅ Reusable code in `services/` (DRY principle)
+- ✅ Centralized type definitions
+
+---
+
+## Workflow Files
+
+### 1. Webhook Workflow (`src/workflows/webhook/order-cancel.ts`)
+
+**Purpose**: Handle order cancel requests via webhook
+**Trigger**: HTTP POST
+**Endpoint**: `POST https://{workspace}.versori.run/order-cancel`
+**Use Cases**: Order cancellation from external systems, manual cancellations
+
+```typescript
+import { webhook, http } from '@versori/run';
+import { executeOrderCancel } from '../../services/order-cancel.service';
+
+/**
+ * Webhook: Order Cancel Handler
+ *
+ * Endpoint: POST https://{workspace}.versori.run/order-cancel
+ * Request body: { "orderRef": "ORD-12345" }
+ *
+ * Pattern: webhook().then(http()) - needs Fluent API access
+ * Uses shared service: order-cancel.service.ts
+ *
+ * SECURITY: Authentication handled via connection parameter
+ * No manual API key validation needed - Versori manages this via connection auth
+ */
+export const orderCancelWebhook = webhook('order-cancel', {
+  // ✅ Webhook response mode: 'sync'
+  //    - HTTP response sent when handler completes
+  //    - Returns event ID and success status immediately after Fluent accepts event
+  //    - Alternative: 'async' mode would return immediately (before processing)
+  response: { mode: 'sync' },
+  connection: 'order-cancel-webhook', // Versori validates API key
+}).then(
+  http('process-order-cancel', { connection: 'fluent_commerce' }, async ctx => {
+    const { log, data } = ctx;
+
+    log.info('🚀 [WEBHOOK] Order cancel request received', {
+      timestamp: new Date().toISOString(),
+      hasPayload: !!data,
+    });
+
+    try {
+      // Reuse shared orchestration logic
+      const result = await executeOrderCancel(ctx);
+
+      log.info('✅ [WEBHOOK] Order cancel completed successfully', {
+        orderRef: result.orderRef,
+        eventId: result.eventId,
+      });
+
+      return {
+        success: true,
+        orderRef: result.orderRef,
+        eventId: result.eventId,
+        message: 'Order cancel event sent successfully',
+      };
+    } catch (e: any) {
+      log.error('❌ [WEBHOOK] Order cancel failed', {
+        message: e?.message,
+        stack: e?.stack,
+      });
+
+      return {
+        success: false,
+        error: e?.message || 'Unknown error occurred',
+      };
+    }
+  })
+);
+```
+
+---
+
+### 2. Entry Point (`index.ts`)
+
+**Purpose**: Register all workflows with Versori platform
+
+```typescript
+/**
+ * Entry Point - Registers all workflows with Versori platform
+ *
+ * Versori automatically discovers and registers exported workflows
+ *
+ * File Structure:
+ * - src/workflows/webhook/   → HTTP-based triggers (webhooks)
+ * - src/services/            → Shared service logic (reusable across workflows)
+ */
+
+// Import webhook workflows
+import { orderCancelWebhook } from './src/workflows/webhook/order-cancel';
+
+// Register all workflows with Versori platform
+export {
+  // Webhooks (HTTP-based triggers)
+  orderCancelWebhook,
+};
+```
+
+**What Gets Exposed:**
+- ✅ `orderCancelWebhook` → `https://{workspace}.versori.run/order-cancel`
+
+---
+
+## 3. Type Definitions (`src/types/order-cancel.types.ts`)
+
+```typescript
+/**
+ * Type Definitions for Order Cancel Ingestion
+ *
+ * Centralized type definitions for order cancel workflow
+ */
+
+/**
+ * Order cancel request payload
+ */
+export interface OrderCancelPayload {
+  orderRef?: string;
+  order?: {
+    reference?: string;
+    ref?: string;
+  };
+  [key: string]: unknown; // Allow additional fields
+}
+
+/**
+ * Order cancel event payload
+ */
+export interface OrderCancelEvent {
+  retailerId: string;
+  name: 'OrderCancel';
+  entityRef: string;
+  entityType: 'ORDER';
+}
+
+/**
+ * Order cancel result
+ */
+export interface OrderCancelResult {
+  success: boolean;
+  orderRef: string;
+  eventId?: string;
+  error?: string;
+}
+
+/**
+ * Versori Context Interface
+ * Represents the Versori runtime context passed to workflow functions
+ */
+export interface VersoriContext {
+  log: {
+    info: (message: string, data?: Record<string, unknown>) => void;
+    warn: (message: string, data?: Record<string, unknown>) => void;
+    error: (message: string, data?: Record<string, unknown>) => void;
+    debug?: (message: string, data?: Record<string, unknown>) => void;
+  };
+  data?: unknown;
+  request?: Request;
+  activation: {
+    getVariable: (name: string) => string | undefined;
+    connections?: Record<string, unknown>;
+  };
+  connections?: Record<string, unknown>;
+}
+```
+
+---
+
+## 4. Service: Order Cancel Processor (`src/services/order-cancel.service.ts`)
+
+```typescript
+/**
+ * Order Cancel Service
+ *
+ * Processes order cancel requests: extracts order reference from JSON payload,
+ * builds OrderCancel event, and sends to Fluent Commerce Event API.
+ */
+
+import {
+  createClient,
+  JSONParserService,
+} from '@fluentcommerce/fc-connect-sdk';
+import type { FluentClient } from '@fluentcommerce/fc-connect-sdk';
+import type {
+  OrderCancelPayload,
+  OrderCancelResult,
+  VersoriContext,
+} from '../types/order-cancel.types';
+
+/**
+ * Extract order reference from JSON payload
+ *
+ * Supports multiple payload formats:
+ * - { orderRef: "ORD-12345" }
+ * - { order: { reference: "ORD-12345" } }
+ * - { order: { ref: "ORD-12345" } }
+ */
+function extractOrderRef(payload: OrderCancelPayload): string | null {
+  // Try direct orderRef field
+  if (payload.orderRef && typeof payload.orderRef === 'string') {
+    return payload.orderRef;
+  }
+
+  // Try nested order.reference
+  if (
+    payload.order &&
+    typeof payload.order === 'object' &&
+    'reference' in payload.order
+  ) {
+    const ref = payload.order.reference;
+    if (typeof ref === 'string') {
+      return ref;
+    }
+  }
+
+  // Try nested order.ref
+  if (
+    payload.order &&
+    typeof payload.order === 'object' &&
+    'ref' in payload.order
+  ) {
+    const ref = payload.order.ref;
+    if (typeof ref === 'string') {
+      return ref;
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse webhook payload from Versori context
+ *
+ * Handles both pre-parsed JSON (ctx.data) and raw request body (ctx.request)
+ */
+async function parseWebhookPayload(
+  ctx: VersoriContext
+): Promise<OrderCancelPayload | null> {
+  const { log, data, request } = ctx;
+
+  // Scenario 1: Pre-parsed JSON (Versori auto-parsed)
+  if (data && typeof data === 'object') {
+    log.info('📥 [PARSE] Using pre-parsed JSON payload', {
+      hasData: true,
+      dataKeys: Object.keys(data),
+    });
+    return data as OrderCancelPayload;
+  }
+
+  // Scenario 2: Raw request body (need to parse)
+  if (request && typeof request.text === 'function') {
+    log.info('📥 [PARSE] Extracting raw request body');
+    try {
+      const rawBody = await request.text();
+      if (!rawBody || rawBody.trim() === '') {
+        log.error('❌ [PARSE] Request body is empty');
+        return null;
+      }
+
+      const parser = new JSONParserService(log);
+      const parsed = await parser.parse(rawBody);
+      
+      log.info('📥 [PARSE] Successfully parsed JSON payload', {
+        parsedKeys: Object.keys(parsed),
+      });
+      
+      return parsed as OrderCancelPayload;
+    } catch (parseError: unknown) {
+      const errorMessage =
+        parseError instanceof Error ? parseError.message : String(parseError);
+      log.error('❌ [PARSE] Failed to parse JSON payload', {
+        error: errorMessage,
+      });
+      return null;
+    }
+  }
+
+  log.error('❌ [PARSE] No valid payload found in context');
+  return null;
+}
+
+/**
+ * Build OrderCancel event payload
+ */
+function buildOrderCancelEvent(
+  orderRef: string,
+  retailerId: string
+): {
+  retailerId: string;
+  name: 'OrderCancel';
+  entityRef: string;
+  entityType: 'ORDER';
+} {
+  return {
+    retailerId,
+    name: 'OrderCancel',
+    entityRef: orderRef,
+    entityType: 'ORDER',
+  };
+}
+
+/**
+ * Execute order cancel workflow
+ *
+ * Main orchestration function:
+ * 1. Parse webhook payload
+ * 2. Extract order reference
+ * 3. Create Fluent client
+ * 4. Build event payload
+ * 5. Send event to Fluent Commerce
+ */
+export async function executeOrderCancel(
+  ctx: VersoriContext
+): Promise<OrderCancelResult> {
+  const { log, activation } = ctx;
+
+  log.info('🚀 [SERVICE] Starting order cancel processing');
+
+  // STEP 1: Parse webhook payload
+  const payload = await parseWebhookPayload(ctx);
+  if (!payload) {
+    log.error('❌ [SERVICE] Failed to parse webhook payload', {
+      hasData: !!ctx.data,
+      hasRequest: !!ctx.request,
+    });
+    throw new Error('Failed to parse webhook payload. Ensure Content-Type: application/json is set in request headers.');
+  }
+
+  log.info('📥 [SERVICE] Payload parsed successfully', {
+    payloadKeys: Object.keys(payload),
+  });
+
+  // STEP 2: Extract order reference
+  const orderRef = extractOrderRef(payload);
+  if (!orderRef) {
+    log.error('❌ [SERVICE] Order reference not found in payload', {
+      payloadKeys: Object.keys(payload),
+      expectedFields: ['orderRef', 'order.reference', 'order.ref'],
+    });
+    throw new Error(
+      'Order reference not found in payload. Expected field: orderRef, order.reference, or order.ref'
+    );
+  }
+
+  log.info('✅ [SERVICE] Order reference extracted', { orderRef });
+
+  // STEP 3: Get retailer ID from activation variable or connection
+  const retailerId =
+    activation.getVariable('FLUENT_RETAILER_ID') ||
+    (activation.connections?.fluent_commerce as any)?.retailerId;
+
+  if (!retailerId) {
+    log.error('❌ [SERVICE] Retailer ID not found', {
+      checkedVariables: ['FLUENT_RETAILER_ID'],
+      hasConnection: !!activation.connections?.fluent_commerce,
+    });
+    throw new Error(
+      'Retailer ID not found. Set FLUENT_RETAILER_ID activation variable or configure in connection.'
+    );
+  }
+
+  log.info('✅ [SERVICE] Retailer ID retrieved', { retailerId });
+
+  // STEP 4: Create Fluent client
+  // ✅ Pass ctx directly - createClient auto-detects Versori context
+  const client = await createClient(ctx);
+
+  log.info('✅ [SERVICE] Fluent client created');
+
+  // STEP 5: Build event payload
+  const eventPayload = buildOrderCancelEvent(orderRef, retailerId);
+
+  log.info('📤 [SERVICE] Sending OrderCancel event', {
+    orderRef,
+    retailerId,
+  });
+
+  // STEP 6: Send event to Fluent Commerce
+  // ✅ Using 'async' mode (recommended):
+  //    - Fluent accepts event immediately and processes in background
+  //    - Returns event ID quickly (non-blocking)
+  //    - Better performance for webhook responses
+  //    - Alternative: 'sync' mode waits for event processing (slower, blocking)
+  //      - Sync mode success: { eventId: "...", eventStatus: "COMPLETE" }
+  //      - Sync mode failure: { eventStatus: "FAILED" }
+  //      - Sync mode no match: { eventId: "...", eventStatus: "NO_MATCH" }
+  const response = await client.sendEvent(eventPayload, 'async');
+
+  // Extract event ID from Fluent response
+  // Async mode response format: { id: "evt_abc123", ... }
+  // Sync mode response format (success): { eventId: "...", eventStatus: "COMPLETE" }
+  // Sync mode response format (failure): { eventStatus: "FAILED" }
+  // Sync mode response format (no match): { eventId: "...", eventStatus: "NO_MATCH" }
+  let eventId: string | undefined;
+  
+  if (response && typeof response === 'object') {
+    // Extract event ID first (needed for error messages)
+    if ('id' in response) {
+      eventId = response.id as string;
+    } else if ('eventId' in response) {
+      eventId = response.eventId as string;
+    }
+    
+    // Check for sync mode failure statuses
+    if ('eventStatus' in response) {
+      const eventStatus = response.eventStatus as string;
+      
+      if (eventStatus === 'FAILED') {
+        log.error('❌ [SERVICE] OrderCancel event failed (sync mode)', {
+          orderRef,
+          eventId,
+          eventStatus,
+          response,
+        });
+        throw new Error('Order cancel event failed. Event status: FAILED');
+      }
+      
+      if (eventStatus === 'NO_MATCH') {
+        log.error('❌ [SERVICE] OrderCancel event no match (sync mode)', {
+          orderRef,
+          eventId,
+          eventStatus,
+          response,
+        });
+        throw new Error(
+          'Order cancel event did not match any workflow. Possible causes: incorrect event name, status mismatch, or entity not found. Event status: NO_MATCH'
+        );
+      }
+      
+      if (eventStatus === 'COMPLETE') {
+        log.info('✅ [SERVICE] OrderCancel event completed (sync mode)', {
+          orderRef,
+          eventId,
+          eventStatus,
+        });
+      }
+    }
+  }
+
+  log.info('✅ [SERVICE] OrderCancel event sent successfully', {
+    orderRef,
+    eventId,
+  });
+
+  return {
+    success: true,
+    orderRef,
+    eventId,
+  };
+}
+```
+
+---
+
+## 5. Configuration
+
+### Activation Variables
+
+Configure these variables in Versori activation settings:
+
+```json
+{
+  "FLUENT_RETAILER_ID": "your-retailer-id"
+}
+```
+
+**Note:** If using Versori connection for Fluent Commerce, retailer ID can also be configured in the connection settings.
+
+### Webhook Connection
+
+Create a Versori connection for webhook authentication:
+
+1. **Connection Name:** `order-cancel-webhook`
+2. **Type:** API Key or Basic Auth
+3. **Purpose:** Authenticate incoming webhook requests
+
+**Example webhook call:**
+
+```bash
+curl -X POST https://{workspace}.versori.run/order-cancel \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your-api-key" \
+  -d '{
+    "orderRef": "ORD-12345"
+  }'
+```
+
+---
+
+## 6. Error Handling
+
+The template includes comprehensive error handling:
+
+### Payload Parsing Errors
+
+- **Empty payload:** Returns error response
+- **Invalid JSON:** Returns error with parse details
+- **Missing order reference:** Returns error with expected field names
+
+### Event Sending Errors
+
+- **Network errors:** Logged and returned in error response
+- **API errors:** Logged with full error details
+- **Validation errors:** Logged with validation message
+
+### Error Response Format
+
+**Webhook Processing Errors:**
+```json
+{
+  "success": false,
+  "error": "Order reference not found in payload. Expected field: orderRef, order.reference, or order.ref"
+}
+```
+
+**Event API Sync Mode Responses:**
+
+**Success (sync mode):**
+```json
+{
+  "eventId": "421d1709-d0af-4d8a-b7b6-75e40c5fc038",
+  "eventStatus": "COMPLETE"
+}
+```
+
+**Failure (sync mode):**
+```json
+{
+  "eventStatus": "FAILED"
+}
+```
+
+**No Match (sync mode):**
+Occurs when event name is incorrect, status mismatch, or entity not found:
+```json
+{
+  "eventId": "9782c552-033c-47c7-89ea-2b0068fbdd0a",
+  "eventStatus": "NO_MATCH"
+}
+```
+
+The webhook will catch failures and return:
+```json
+{
+  "success": false,
+  "error": "Order cancel event failed. Event status: FAILED"
+}
+```
+
+Or for NO_MATCH:
+```json
+{
+  "success": false,
+  "error": "Order cancel event did not match any workflow. Possible causes: incorrect event name, status mismatch, or entity not found. Event status: NO_MATCH"
+}
+```
+
+---
+
+## 7. Testing
+
+### Test with cURL
+
+```bash
+# Test order cancel webhook
+curl -X POST https://{workspace}.versori.run/order-cancel \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: your-api-key" \
+  -d '{
+    "orderRef": "ORD-12345"
+  }'
+```
+
+### Expected Success Response
+
+```json
+{
+  "success": true,
+  "orderRef": "ORD-12345",
+  "eventId": "evt_abc123",
+  "message": "Order cancel event sent successfully"
+}
+```
+
+**Response Details:**
+- `success`: `true` indicates webhook processed successfully
+- `orderRef`: The order reference that was cancelled
+- `eventId`: Fluent Commerce event ID (returned from Event API async endpoint)
+- `message`: Human-readable success message
+
+**Event API Mode: `async` (recommended)**
+- Fluent accepts the event immediately and returns an event ID
+- Event processing happens in the background
+- Webhook response includes the event ID for tracking
+- Response format: `{ id: "evt_abc123" }`
+
+**Alternative: `sync` mode**
+- Fluent processes the event synchronously before responding
+- Slower response time (waits for event processing)
+- Success response: `{ eventId: "...", eventStatus: "COMPLETE" }`
+- Failure response: `{ eventStatus: "FAILED" }`
+- No match response: `{ eventId: "...", eventStatus: "NO_MATCH" }` (incorrect event name, status mismatch, or entity not found)
+- Use only if you need immediate confirmation of event processing
+
+### Expected Error Response
+
+```json
+{
+  "success": false,
+  "error": "Order reference not found in payload"
+}
+```
+
+---
+
+## 8. Customization
+
+### Custom Order Reference Field
+
+If your payload uses a different field name, modify `extractOrderRef()` in `order-cancel.service.ts`:
+
+```typescript
+function extractOrderRef(payload: OrderCancelPayload): string | null {
+  // Add your custom field extraction logic
+  if (payload.customOrderId && typeof payload.customOrderId === 'string') {
+    return payload.customOrderId;
+  }
+  // ... existing logic
+}
+```
+
+### Custom Event Name
+
+To use a different event name, modify `buildOrderCancelEvent()`:
+
+```typescript
+function buildOrderCancelEvent(
+  orderRef: string,
+  retailerId: string
+) {
+  return {
+    retailerId,
+    name: 'CustomOrderCancel', // Change event name
+    entityRef: orderRef,
+    entityType: 'ORDER',
+  };
+}
+```
+
+### Additional Event Data
+
+To include additional data in the event:
+
+```typescript
+function buildOrderCancelEvent(
+  orderRef: string,
+  retailerId: string,
+  additionalData?: Record<string, unknown>
+) {
+  return {
+    retailerId,
+    name: 'OrderCancel',
+    entityRef: orderRef,
+    entityType: 'ORDER',
+    data: additionalData, // Add custom data
+  };
+}
+```
+
+---
+
+## Summary
+
+✅ **DO:**
+- Use Versori connection for Fluent Commerce credentials
+- Handle both pre-parsed and raw JSON payloads
+- Extract order reference with fallback patterns
+- Log all steps for debugging
+- Return clear error messages
+
+❌ **DON'T:**
+- Hardcode credentials in code
+- Assume payload format without validation
+- Skip error handling
+- Use `sync` mode for Event API (use `async` for better performance and faster webhook responses)
+
+---
+
+## Next Steps
+
+1. **Deploy:** Copy code to your Versori project
+2. **Configure:** Set up Fluent Commerce connection and activation variables
+3. **Test:** Test webhook with sample payloads
+4. **Monitor:** Check Versori logs for event processing
+
+For more templates, see:
+- [XML Payload Template](./template-ingestion-payload-xml-order-cancel-event.md)
+- [Other Event API Templates](./event-api-guide.md)
+