@fluentcommerce/fc-connect-sdk 0.1.54 → 0.1.55

package/docs/03-PATTERN-GUIDES/integration-patterns/modules/integration-patterns-04-webhook-patterns.md

@@ -1,1181 +1,1181 @@
-# Module 4: Webhook Patterns
-
-> **Learning Objective:** Master webhook integration patterns for event-driven architectures, including request parsing, response formatting, and error handling.
->
-> **Level:** Intermediate
-
-## Table of Contents
-
-1. [What are Webhooks?](#what-are-webhooks)
-2. [Webhook Types and Patterns](#webhook-types-and-patterns)
-3. [SDK Webhook Components](#sdk-webhook-components)
-4. [Pattern 1: JSON Request/Response](#pattern-1-json-requestresponse)
-5. [Pattern 2: XML Request/Response](#pattern-2-xml-requestresponse)
-6. `Pattern 3: Mixed Format (XML→JSON)`
-7. [Versori Webhook Response Handling](#versori-webhook-response-handling)
-8. [Webhook Security](#webhook-security)
-9. [Error Handling and Retry Logic](#error-handling-and-retry-logic)
-10. [Complete Examples](#complete-examples)
-11. [Next Steps](#next-steps)
-
----
-
-## What are Webhooks?
-
-**Webhooks** are HTTP endpoints that receive event notifications from external systems in real-time.
-
-### Webhook Flow
-
-```
-External System         Your Webhook           Fluent Commerce
-     │                       │                        │
-     │  ① Event occurs       │                        │
-     │  (order placed)       │                        │
-     │                       │                        │
-     │  ② HTTP POST ────────>│                        │
-     │     Payload (XML/JSON)│                        │
-     │                       │                        │
-     │                       │  ③ Parse payload       │
-     │                       │  ④ Transform data      │
-     │                       │                        │
-     │                       │  ⑤ GraphQL mutation ──>│
-     │                       │                        │
-     │                       │<── ⑥ Response          │
-     │                       │                        │
-     │<── ⑦ 200 OK          │                        │
-     │     Success message   │                        │
-```
-
-### Key Characteristics
-
-| Characteristic   | Description                  | Example                |
-| ---------------- | ---------------------------- | ---------------------- |
-| **Push-Based**   | External system initiates    | SFCC pushes order      |
-| **Event-Driven** | Triggered by specific events | Order created, shipped |
-| **Synchronous**  | Caller waits for response    | Return 200 OK or 500   |
-| **Real-Time**    | Immediate processing         | < 5 second response    |
-
----
-
-## Webhook Types and Patterns
-
-### By Input Format
-
-| Type          | Content-Type                        | Example Source  | SDK Parser         |
-| ------------- | ----------------------------------- | --------------- | ------------------ |
-| **JSON**      | `application/json`                  | Shopify, Stripe | Native JSON.parse  |
-| **XML**       | `application/xml`                   | SFCC, Radial    | `XMLParserService` |
-| **Form Data** | `application/x-www-form-urlencoded` | Older systems  | URLSearchParams    |
-| **Multipart** | `multipart/form-data`               | File uploads    | Not supported      |
-
-### By Response Format
-
-| Type           | Content-Type       | Use Case        | Pattern         |
-| -------------- | ------------------ | --------------- | --------------- |
-| **JSON**       | `application/json` | API responses   | Default         |
-| **XML**        | `application/xml`  | SOAP/EDI     | Custom Response |
-| **HTML**       | `text/html`        | Browser display | Custom Response |
-| **Plain Text** | `text/plain`       | Simple status   | Custom Response |
-
-### By Processing Pattern
-
-| Pattern             | Latency            | Complexity | Example                        |
-| ------------------- | ------------------ | ---------- | ------------------------------ |
-| **Immediate**       | < 2 sec            | Low        | Status update                  |
-| **Transformation**  | 2-5 sec            | Medium     | XML → GraphQL                  |
-| **Lookup & Create** | 3-10 sec           | High       | Customer lookup + order create |
-| **Async**           | Return immediately | High       | Queue for later processing     |
-
----
-
-## SDK Webhook Components
-
-### Component 1: `XMLParserService`
-
-**Purpose**: Parse XML payloads (SFCC, Radial, SOAP)
-
-```typescript
-import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
-
-const parser = new XMLParserService({
-  ignoreAttributes: false, // Keep XML attributes
-  attributeNamePrefix: '@', // Prefix for attributes
-  textNodeName: '_', // Text content key
-  parseAttributeValue: true, // Parse attribute values
-});
-
-// Parse XML string
-const xmlData = await parser.parse(xmlString);
-
-// Parse with path resolution
-const value = await parser.parseWithPath(xmlString, 'order.items.item[0].sku');
-```
-
-### Component 2: `GraphQLMutationMapper`
-
-**Purpose**: Transform XML/JSON to GraphQL mutations
-
-```typescript
-import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
-
-const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
-
-// Process with nodes (extract nested/escaped XML)
-const result = await mapper.mapWithNodes(sourceData, customResolvers, context);
-
-// Check success (errors are returned, not thrown)
-if (!result.success) {
-  console.error('Mapping failed:', result.errors);
-  return;
-}
-
-// Execute (query is auto-generated in result)
-const data = await client.graphql({ 
-  query: result.query, 
-  variables: result.variables  // ✅ Use variables (wrapped if fields pattern)
-});
-```
-
-**Key features**:
-
-- **Nodes**: Extract nested XML before mapping
-- **Path Resolution**: Navigate complex XML/JSON structures
-- **Custom Resolvers**: Apply business logic (async supported)
-- **Validation**: Required fields and types
-
-### Component 3: `createClient()`
-
-**Purpose**: Create authenticated Fluent client
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-// Versori platform
-const client = await createClient({
-  connection: connections.fluent_commerce,
-  logger: log,
-});
-
-// Standalone
-const client = await createClient({
-  config: {
-    baseUrl: 'https://api.fluentcommerce.com',
-    clientId: process.env.FLUENT_CLIENT_ID,
-    clientSecret: process.env.FLUENT_CLIENT_SECRET,
-    retailerId: process.env.FLUENT_RETAILER_ID,
-  },
-});
-```
-
-### Component 4: Versori Webhook Utilities
-
-**Available in Versori platform**:
-
-```typescript
-import { webhook, fn, http } from '@versori/run';
-
-// Create webhook endpoint
-export const orderWebhook = webhook('order-create', async ctx => {
-  const orderData = ctx.request.body;
-  // Process order
-  return { success: true };
-});
-
-// With custom response handlers
-export const xmlWebhook = webhook('xml-endpoint', {
-  response: {
-    mode: 'sync',
-    onSuccess: ctx =>
-      new Response(ctx.data, {
-        status: 200,
-        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
-      }),
-  },
-}).then(
-  fn('process', async ctx => {
-    // Process data
-    return '<response>Success</response>';
-  })
-);
-```
-
----
-
-## Pattern 1: JSON Request/Response
-
-### Use Case
-
-**Modern APIs** (Shopify, Stripe, custom REST APIs) sending JSON webhooks.
-
-### Implementation
-
-```typescript
-/**
- * JSON Webhook: Shopify Order → Fluent Order
- *
- * Input: application/json
- * Output: application/json
- */
-
-import { createClient, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
-
-export default async function shopifyOrderWebhook(activation: any, log: any, connections: any) {
-  try {
-    // Step 1: Extract JSON payload (Versori auto-parses)
-    const shopifyOrder = activation.body;
-
-    log.info('Received Shopify order', {
-      orderId: shopifyOrder.id,
-      orderNumber: shopifyOrder.order_number,
-    });
-
-    // Step 2: Validate payload
-    if (!shopifyOrder.id || !shopifyOrder.line_items) {
-      throw new Error('Invalid Shopify order payload');
-    }
-
-    // Step 3: Create Fluent client
-    const client = await createClient({
-      connection: connections.fluent_commerce,
-      logger: log,
-    });
-
-    // Step 4: Map Shopify → Fluent
-    const mapper = new UniversalMapper(
-      {
-        fields: {
-          ref: { source: 'order_number', required: true },
-          type: { value: 'HD' },
-          totalPrice: { source: 'total_price', resolver: 'sdk.parseFloat' },
-          currency: { source: 'currency' },
-          'retailer.id': { value: '2' },
-          'customer.id': { resolver: 'custom.lookupCustomer' },
-          'items[]': {
-            source: 'line_items',
-            fields: {
-              ref: { source: '$.id', resolver: 'sdk.toString' },
-              productRef: { source: '$.sku', required: true },
-              quantity: { source: '$.quantity', resolver: 'sdk.parseInt' },
-              price: { source: '$.price', resolver: 'sdk.parseFloat' },
-              currency: { source: '^.currency' },
-            },
-          },
-        },
-      },
-      {
-        customResolvers: {
-          'custom.lookupCustomer': async (value, data, config, helpers) => {
-            const email = data.customer?.email;
-            if (!email) return null;
-
-            // Query for customer
-            const result = await helpers.fluentClient.graphql({
-              query: `query GetCustomer($email: String) {
-              customers(primaryEmail: $email, first: 1) {
-                edges { node { id } }
-              }
-            }`,
-              variables: { email },
-            });
-
-            return result?.customers?.edges?.[0]?.node?.id || null;
-          },
-        },
-      }
-    );
-
-    // map() returns GraphQLPayload { query, variables } - ready to execute!
-    const mapResult = await mapper.map(shopifyOrder, {
-      fluentClient: client,
-    });
-
-    // Step 5: Create order in Fluent (mapResult already has query + variables)
-    const order = await client.graphql(mapResult);
-
-    log.info('Order created in Fluent', {
-      fluentOrderId: order.id,
-      fluentOrderRef: order.ref,
-    });
-
-    // Step 6: Return JSON response
-    return {
-      status: 200,
-      body: {
-        success: true,
-        shopifyOrderId: shopifyOrder.id,
-        fluentOrderId: order.id,
-        fluentOrderRef: order.ref,
-      },
-    };
-  } catch (error: any) {
-    log.error('Shopify webhook failed', error);
-
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: error.message,
-      },
-    };
-  }
-}
-```
-
-### Example Payload
-
-**Input** (Shopify webhook):
-
-```json
-{
-  "id": 12345678,
-  "order_number": "SO-1001",
-  "total_price": "159.98",
-  "currency": "USD",
-  "customer": {
-    "email": "customer@example.com"
-  },
-  "line_items": [
-    {
-      "id": 111,
-      "sku": "SKU-001",
-      "quantity": 2,
-      "price": "79.99"
-    }
-  ]
-}
-```
-
-**Output**:
-
-```json
-{
-  "success": true,
-  "shopifyOrderId": 12345678,
-  "fluentOrderId": "1234",
-  "fluentOrderRef": "SO-1001"
-}
-```
-
----
-
-## Pattern 2: XML Request/Response
-
-### Use Case
-
-**Older systems** (SFCC, Radial, SOAP) sending XML webhooks and expecting XML responses.
-
-### Implementation
-
-See complete implementation: [XML Order Ingestion](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
-
-### Quick Example
-
-```typescript
-/**
- * XML Webhook: SFCC Order → Fluent Order → XML Response
- *
- * Input: application/xml
- * Output: application/xml
- */
-
-import {
-  createClient,
-  GraphQLMutationMapper,
-  XMLParserService,
-} from '@fluentcommerce/fc-connect-sdk';
-import { webhook, fn } from '@versori/run';
-import { XMLBuilder } from 'fast-xml-parser';
-
-export const sfccOrderWebhook = webhook('sfcc-order', {
-  response: {
-    mode: 'sync',
-    // CRITICAL: Custom response handler for XML (not JSON)
-    onSuccess: ctx =>
-      new Response(ctx.data, {
-        status: 200,
-        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
-      }),
-    onError: ctx =>
-      new Response(ctx.data, {
-        status: 500,
-        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
-      }),
-  },
-})
-  .then(
-    fn('process-order', async ctx => {
-      const { body } = ctx.request;
-      const { log, connections } = ctx;
-
-      try {
-        // Parse XML (Versori pre-parses, but you can re-parse if needed)
-        const parser = new XMLParserService();
-        const orderData = typeof body === 'string' ? await parser.parse(body) : body;
-
-        // Create client
-        const client = await createClient({
-          connection: connections.fluent_commerce,
-          logger: log,
-        });
-
-        // Map XML → GraphQL
-        const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
-        const result = await mapper.mapWithNodes(orderData, customResolvers, {
-          fluentClient: client,
-        });
-
-        if (!result.success) {
-          throw new Error(`Mapping failed: ${result.errors?.join(', ')}`);
-        }
-
-        // Execute mutation (query is auto-generated in result)
-        const order = await client.graphql({
-          query: result.query,
-          variables: result.variables,  // ✅ Use variables (wrapped if fields pattern)
-        });
-
-        // Build XML response
-        const builder = new XMLBuilder({
-          ignoreAttributes: false,
-          attributeNamePrefix: '@',
-        });
-
-        const xmlResponse = builder.build({
-          OrderResponse: {
-            '@status': 'success',
-            OrderId: order.id,
-            OrderRef: order.ref,
-            Message: 'Order created successfully',
-          },
-        });
-
-        return `<?xml version="1.0" encoding="UTF-8"?>\n${xmlResponse}`;
-      } catch (error: any) {
-        log.error('SFCC order processing failed', error);
-
-        // Build XML error response
-        const builder = new XMLBuilder({ ignoreAttributes: false });
-        const xmlError = builder.build({
-          OrderResponse: {
-            '@status': 'error',
-            ErrorMessage: error.message,
-          },
-        });
-
-        throw new Error(`<?xml version="1.0" encoding="UTF-8"?>\n${xmlError}`);
-      }
-    })
-  )
-  .catch(({ data }) => {
-    // Return error XML (already formatted in catch block)
-    return data;
-  });
-```
-
-**Why custom response handler?**
-
-Versori's default behavior JSON-encodes all responses. For XML, you must use `Response` objects with proper Content-Type.
-
-See: [Versori Webhook Response Patterns](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)
-
----
-
-## Pattern 3: Mixed Format (XML→JSON)
-
-### Use Case
-
-**Older system input, modern output**: Receive XML webhook, return JSON response.
-
-### Implementation
-
-```typescript
-/**
- * Mixed Format Webhook: XML Input → JSON Output
- *
- * Input: application/xml
- * Output: application/json
- */
-
-import {
-  createClient,
-  GraphQLMutationMapper,
-  XMLParserService,
-} from '@fluentcommerce/fc-connect-sdk';
-
-export default async function mixedFormatWebhook(activation: any, log: any, connections: any) {
-  try {
-    // Parse XML input
-    const parser = new XMLParserService();
-    const xmlData =
-      typeof activation.body === 'string' ? await parser.parse(activation.body) : activation.body;
-
-    log.info('Parsed XML payload', { rootKeys: Object.keys(xmlData) });
-
-    // Create client
-    const client = await createClient({
-      connection: connections.fluent_commerce,
-      logger: log,
-    });
-
-    // Map XML → GraphQL
-    const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
-    const result = await mapper.mapWithNodes(xmlData, customResolvers, {
-      fluentClient: client,
-    });
-
-    if (!result.success) {
-      throw new Error(`Mapping failed: ${result.errors?.join(', ')}`);
-    }
-
-    // Execute mutation (query is auto-generated in result)
-    const order = await client.graphql({
-      query: result.query,
-      variables: result.variables,  // ✅ Use variables (wrapped if fields pattern)
-    });
-
-    // Return JSON response (default Versori behavior)
-    return {
-      status: 200,
-      body: {
-        success: true,
-        orderId: order.id,
-        orderRef: order.ref,
-        message: 'Order created successfully',
-      },
-    };
-  } catch (error: any) {
-    log.error('Webhook processing failed', error);
-
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: error.message,
-      },
-    };
-  }
-}
-```
-
----
-
-## Versori Webhook Response Handling
-
-### Critical Pattern: Non-JSON Responses
-
-**Problem**: Versori default handlers JSON-encode all responses.
-
-**Solution**: Use custom `onSuccess`/`onError` handlers with `Response` objects.
-
-### XML Response Pattern
-
-```typescript
-export const xmlEndpoint = webhook('xml', {
-  response: {
-    mode: 'sync',
-    onSuccess: ctx =>
-      new Response(ctx.data, {
-        status: 200,
-        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
-      }),
-    onError: ctx =>
-      new Response(ctx.data, {
-        status: 500,
-        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
-      }),
-  },
-})
-  .then(fn('gen', () => '<?xml version="1.0"?><response>Success</response>'))
-  .catch(({ data }) => '<error>Failed</error>');
-```
-
-### HTML Response Pattern
-
-```typescript
-export const htmlEndpoint = webhook('html', {
-  response: {
-    mode: 'sync',
-    onSuccess: ctx =>
-      new Response(ctx.data, {
-        status: 200,
-        headers: { 'Content-Type': 'text/html; charset=utf-8' },
-      }),
-  },
-}).then(fn('gen', () => '<!DOCTYPE html><html><body>OK</body></html>'));
-```
-
-### CSV Download Pattern
-
-```typescript
-export const csvEndpoint = webhook('csv', {
-  response: {
-    mode: 'sync',
-    onSuccess: ctx =>
-      new Response(ctx.data, {
-        status: 200,
-        headers: {
-          'Content-Type': 'text/csv; charset=utf-8',
-          'Content-Disposition': 'attachment; filename="data.csv"',
-        },
-      }),
-  },
-}).then(fn('gen', () => 'ID,Name,Value\n1,Item,100'));
-```
-
-**Complete guide**: [Versori Webhook Response Patterns](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)
-
----
-
-## Webhook Security
-
-### Pattern 1: Fluent Commerce Webhook Validation
-
-⚠️ **CRITICAL LIMITATION:** The SDK's `validateWebhook()` method **ONLY works with Fluent Commerce Rubix webhooks**. Do not use for Shopify, GitHub, Stripe, or other third-party webhooks. See Pattern 3 for those systems.
-
-**Use FluentClient.validateWebhook()** for cryptographic signature validation of **Fluent Commerce webhooks only**.
-
-The SDK provides built-in webhook validation using RSA-based algorithms (SHA512withRSA, MD5withRSA).
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-/**
- * SDK Webhook Validation - Fluent Commerce Only
- *
- * Supports: SHA512withRSA (fluent-signature), MD5withRSA (flex.signature)
- * Does NOT support: Shopify, GitHub, Stripe, or other third-party webhooks
- */
-export default async function secureFluentWebhook(activation: any, log: any, connections: any) {
-  try {
-    // Create client with public key
-    const client = await createClient({
-      connection: connections.fluent_commerce,
-      logger: log,
-      publicKey: process.env.FLUENT_WEBHOOK_PUBLIC_KEY, // Required for webhook validation
-    });
-
-    // Get raw body (CRITICAL: Must be raw string, not parsed JSON)
-    const rawBody = activation.rawBody || JSON.stringify(activation.body);
-    const payload = typeof activation.body === 'string' ? JSON.parse(activation.body) : activation.body;
-
-    // Extract signature from Fluent Commerce headers
-    const signature = activation.headers['fluent-signature'] || activation.headers['flex.signature'];
-
-    if (!signature) {
-      log.error('Missing Fluent Commerce signature header');
-      return { status: 401, body: { error: 'Unauthorized' } };
-    }
-
-    // Validate webhook signature using SDK (Fluent Commerce only)
-    const isValid = await client.validateWebhook(payload, signature, rawBody);
-
-    if (!isValid) {
-      log.error('Invalid Fluent Commerce webhook signature');
-      return { status: 401, body: { error: 'Unauthorized' } };
-    }
-
-    log.info('Fluent Commerce webhook signature validated successfully');
-
-    // Process webhook
-    const result = await processFluentWebhook(payload, client, log);
-
-    return {
-      status: 200,
-      body: {
-        success: true,
-        ...result,
-      },
-    };
-  } catch (error: any) {
-    log.error('Webhook validation or processing failed', error);
-
-    return {
-      status: 500,
-      body: {
-        success: false,
-        error: error.message,
-      },
-    };
-  }
-}
-```
-
-### Fluent Commerce Signature Headers
-
-The SDK automatically detects the signature algorithm from headers:
-
-| Header | Algorithm | Status |
-|--------|-----------|--------|
-| `fluent-signature` | SHA512withRSA | **Recommended** |
-| `x-fluent-signature` | SHA512withRSA | Supported |
-| `flex.signature` | MD5withRSA | **Older algorithm** |
-| `flex-signature` | MD5withRSA | Supported |
-
-```typescript
-// Auto-detection (recommended)
-const signature = headers['fluent-signature'] || headers['flex.signature'];
-const isValid = await client.validateWebhook(payload, signature, rawBody);
-```
-
-### Pattern 2: IP Allowlist (All Webhook Types)
-
-**Restrict webhook sources** to known IP addresses - works for Fluent Commerce, Shopify, GitHub, Stripe, etc.
-
-```typescript
-const ALLOWED_IPS = ['192.168.1.1', '10.0.0.0/8'];
-
-function isIPAllowed(ip: string): boolean {
-  return ALLOWED_IPS.some(allowed => {
-    if (allowed.includes('/')) {
-      // CIDR range check (use ip-cidr library)
-      return true; // Simplified
-    }
-    return ip === allowed;
-  });
-}
-
-// Usage
-export default async function ipRestrictedWebhook(activation: any, log: any) {
-  const clientIP = activation.headers['x-forwarded-for'] || activation.ip;
-
-  if (!isIPAllowed(clientIP)) {
-    log.warn('Blocked request from unauthorized IP', { ip: clientIP });
-    return { status: 403, body: { error: 'Forbidden' } };
-  }
-
-  // Process webhook
-}
-```
-
-### Pattern 3: Third-Party Webhook Validation (Shopify, GitHub, Stripe)
-
-⚠️ **REQUIRED FOR THIRD-PARTY WEBHOOKS:** The SDK's `validateWebhook()` does NOT support HMAC algorithms used by Shopify, GitHub, Stripe. You must implement manual HMAC validation for these systems.
-
-#### Shopify Webhook Validation (HMAC-SHA256, base64)
-
-```typescript
-import crypto from 'crypto';
-
-/**
- * Validate Shopify webhook signature
- * Algorithm: HMAC-SHA256 with base64 encoding
- */
-function validateShopifyWebhook(rawBody: string, signature: string, secret: string): boolean {
-  const hash = crypto
-    .createHmac('sha256', secret)
-    .update(rawBody, 'utf8')
-    .digest('base64');
-
-  return hash === signature;
-}
-
-// Usage
-export default async function shopifyWebhook(activation: any, log: any) {
-  const rawBody = activation.rawBody || JSON.stringify(activation.body);
-  const signature = activation.headers['x-shopify-hmac-sha256'];
-  const secret = process.env.SHOPIFY_WEBHOOK_SECRET!;
-
-  if (!validateShopifyWebhook(rawBody, signature, secret)) {
-    log.error('Invalid Shopify webhook signature');
-    return { status: 401, body: { error: 'Unauthorized' } };
-  }
-
-  // Process webhook
-  const order = await processShopifyOrder(activation.body);
-  return { status: 200, body: { success: true, orderId: order.id } };
-}
-```
-
-#### GitHub Webhook Validation (HMAC-SHA256, hex with prefix)
-
-```typescript
-import crypto from 'crypto';
-
-/**
- * Validate GitHub webhook signature
- * Algorithm: HMAC-SHA256 with hex encoding and sha256= prefix
- */
-function validateGitHubWebhook(rawBody: string, signature: string, secret: string): boolean {
-  const hash = crypto
-    .createHmac('sha256', secret)
-    .update(rawBody, 'utf8')
-    .digest('hex');
-
-  const expected = `sha256=${hash}`;
-  return expected === signature;
-}
-
-// Usage
-export default async function githubWebhook(activation: any, log: any) {
-  const rawBody = activation.rawBody || JSON.stringify(activation.body);
-  const signature = activation.headers['x-hub-signature-256'];
-  const secret = process.env.GITHUB_WEBHOOK_SECRET!;
-
-  if (!validateGitHubWebhook(rawBody, signature, secret)) {
-    log.error('Invalid GitHub webhook signature');
-    return { status: 401, body: { error: 'Unauthorized' } };
-  }
-
-  // Process webhook
-  const result = await processGitHubEvent(activation.body);
-  return { status: 200, body: { success: true } };
-}
-```
-
-#### Stripe Webhook Validation (HMAC-SHA256 with timestamp)
-
-```typescript
-import crypto from 'crypto';
-
-/**
- * Validate Stripe webhook signature
- * Algorithm: HMAC-SHA256 with timestamp verification to prevent replay attacks
- */
-function validateStripeWebhook(
-  rawBody: string,
-  signature: string,
-  secret: string,
-  tolerance: number = 300 // 5 minutes
-): boolean {
-  // Parse signature header: t=timestamp,v1=signature
-  const parts = signature.split(',');
-  const timestamp = parts.find(p => p.startsWith('t='))?.split('=')[1];
-  const sig = parts.find(p => p.startsWith('v1='))?.split('=')[1];
-
-  if (!timestamp || !sig) return false;
-
-  // Check timestamp tolerance (prevent replay attacks)
-  const now = Math.floor(Date.now() / 1000);
-  if (Math.abs(now - parseInt(timestamp)) > tolerance) {
-    return false;
-  }
-
-  // Verify signature
-  const payload = `${timestamp}.${rawBody}`;
-  const hash = crypto
-    .createHmac('sha256', secret)
-    .update(payload, 'utf8')
-    .digest('hex');
-
-  return hash === sig;
-}
-
-// Usage
-export default async function stripeWebhook(activation: any, log: any) {
-  const rawBody = activation.rawBody || JSON.stringify(activation.body);
-  const signature = activation.headers['stripe-signature'];
-  const secret = process.env.STRIPE_WEBHOOK_SECRET!;
-
-  if (!validateStripeWebhook(rawBody, signature, secret)) {
-    log.error('Invalid Stripe webhook signature');
-    return { status: 401, body: { error: 'Unauthorized' } };
-  }
-
-  // Process webhook
-  const result = await processStripeEvent(activation.body);
-  return { status: 200, body: { success: true } };
-}
-```
-
-#### Third-Party Webhook Algorithms
-
-| Provider | Algorithm | Encoding | Header | Notes |
-|----------|-----------|----------|--------|-------|
-| **Shopify** | HMAC-SHA256 | base64 | `x-shopify-hmac-sha256` | Simple HMAC |
-| **GitHub** | HMAC-SHA256 | hex | `x-hub-signature-256` | Prefixed with `sha256=` |
-| **Stripe** | HMAC-SHA256 | hex | `stripe-signature` | Includes timestamp (replay protection) |
-| **PayPal** | HMAC-SHA256 | base64 | `paypal-transmission-sig` | Multiple verification params |
-
-### Error Handling for Validation
-
-```typescript
-// Fluent Commerce webhook validation error handling
-try {
-  const isValid = await client.validateWebhook(payload, signature, rawBody);
-
-  if (!isValid) {
-    log.error('Fluent Commerce webhook signature validation failed', {
-      header: signature ? 'present' : 'missing',
-      algorithm: signature?.includes('fluent-signature') ? 'SHA512withRSA' : 'MD5withRSA',
-    });
-
-    return {
-      status: 401,
-      body: {
-        error: 'Unauthorized',
-        message: 'Invalid webhook signature',
-      },
-    };
-  }
-
-  // Process webhook
-} catch (error: any) {
-  log.error('Webhook validation error', error);
-
-  return {
-    status: 500,
-    body: {
-      error: 'Internal error',
-      message: error.message,
-    },
-  };
-}
-
-// Third-party webhook validation error handling (Shopify example)
-try {
-  const signature = headers['x-shopify-hmac-sha256'];
-  const secret = process.env.SHOPIFY_WEBHOOK_SECRET;
-
-  if (!signature || !secret) {
-    log.error('Missing Shopify webhook credentials');
-    return { status: 401, body: { error: 'Unauthorized' } };
-  }
-
-  const isValid = validateShopifyWebhook(rawBody, signature, secret);
-
-  if (!isValid) {
-    log.error('Shopify webhook signature validation failed');
-    return { status: 401, body: { error: 'Unauthorized' } };
-  }
-
-  // Process webhook
-} catch (error: any) {
-  log.error('Shopify webhook validation error', error);
-  return { status: 500, body: { error: 'Internal error' } };
-}
-```
-
-
-### Pattern 5: API Key Authentication
-
-**Require API key** in headers (alternative to signature validation).
-
-```typescript
-export default async function apiKeyWebhook(activation: any, log: any) {
-  const apiKey = activation.headers['x-api-key'];
-  const expectedKey = process.env.WEBHOOK_API_KEY!;
-
-  if (!apiKey || apiKey !== expectedKey) {
-    log.error('Missing or invalid API key');
-    return { status: 401, body: { error: 'Unauthorized' } };
-  }
-
-  // Process webhook
-}
-```
-
----
-
-## Error Handling and Retry Logic
-
-### HTTP Status Codes
-
-| Status  | Meaning                    | Retry? | Example                   |
-| ------- | -------------------------- | ------ | ------------------------- |
-| **200** | Success                    | No     | Order created             |
-| **400** | Bad Request (client error) | No     | Invalid payload           |
-| **401** | Unauthorized               | No     | Missing/invalid signature |
-| **422** | Unprocessable Entity       | No     | Validation failed         |
-| **429** | Rate Limit                 | Yes    | Too many requests         |
-| **500** | Server Error               | Yes    | Fluent API down           |
-| **503** | Service Unavailable        | Yes    | Temporary outage          |
-
-### Error Response Pattern
-
-```typescript
-try {
-  // Process webhook
-
-  return {
-    status: 200,
-    body: {
-      success: true,
-      orderId: order.id,
-    },
-  };
-} catch (error: any) {
-  // Categorize error
-  if (error.message.includes('required field')) {
-    // Validation error - don't retry
-    return {
-      status: 400,
-      body: {
-        success: false,
-        error: 'Validation failed',
-        details: error.message,
-      },
-    };
-  }
-
-  if (error.message.includes('rate limit')) {
-    // Rate limit - retry after delay
-    return {
-      status: 429,
-      body: {
-        success: false,
-        error: 'Rate limit exceeded',
-        retryAfter: 60,
-      },
-    };
-  }
-
-  // Unknown error - retryable
-  return {
-    status: 500,
-    body: {
-      success: false,
-      error: 'Internal server error',
-      retryable: true,
-    },
-  };
-}
-```
-
-### Idempotency Pattern
-
-**Prevent duplicate processing** of same webhook.
-
-```typescript
-import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
-
-export default async function idempotentWebhook(activation: any, log: any) {
-  const kvAdapter = new VersoriKVAdapter(openKv());
-  const stateService = new StateService(logger);
-
-  // Use webhook ID or order ID as idempotency key
-  const idempotencyKey = `webhook:${activation.body.id}`;
-
-  // Check if already processed
-  const processed = await stateService.getState(idempotencyKey);
-
-  if (processed) {
-    log.info('Webhook already processed', { id: activation.body.id });
-    return {
-      status: 200,
-      body: {
-        success: true,
-        message: 'Already processed',
-        orderId: processed.orderId,
-      },
-    };
-  }
-
-  // Process webhook
-  const order = await processOrder(activation.body);
-
-  // Mark as processed
-  await stateService.setState(idempotencyKey, {
-    orderId: order.id,
-    processedAt: new Date().toISOString(),
-  });
-
-  return {
-    status: 200,
-    body: {
-      success: true,
-      orderId: order.id,
-    },
-  };
-}
-```
-
----
-
-## Complete Examples
-
-### Example 1: Shopify Order Webhook (JSON)
-
-Complete production-ready Shopify integration with:
-
-- JSON parsing
-- Customer lookup/create
-- Order creation
-- Error handling
-
-See: [Common Patterns](../examples/common-patterns.ts)
-
-### Example 2: SFCC Order Webhook (XML)
-
-Complete production-ready SFCC integration with:
-
-- XML parsing with nodes
-- GraphQL mutation mapping
-- Custom resolvers
-- XML response formatting
-
-See: [XML Order Ingestion](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
-
-### Example 3: Inventory Webhook (JSON)
-
-Simple inventory update webhook:
-
-- Single SKU update
-- Direct GraphQL mutation
-- Fast response (< 2 sec)
-
-```typescript
-import { createClient } from '@fluentcommerce/fc-connect-sdk';
-
-export default async function inventoryWebhook(activation: any, log: any, connections: any) {
-  const { sku, location, quantity } = activation.body;
-
-  const client = await createClient({
-    connection: connections.fluent_commerce,
-    logger: log,
-  });
-
-  const result = await client.graphql({
-    query: `
-      mutation UpdateInventory($input: UpdateInventoryQuantityInput!) {
-        updateInventoryQuantity(input: $input) {
-          id
-          ref
-          onHand
-        }
-      }
-    `,
-    variables: {
-      input: {
-        ref: `${sku}-${location}`,
-        onHand: quantity,
-      },
-    },
-  });
-
-  return {
-    status: 200,
-    body: {
-      success: true,
-      inventoryId: result.id,
-      newQuantity: result.onHand,
-    },
-  };
-}
-```
-
----
-
-## Next Steps
-
-Now that you understand webhook patterns, you're ready to learn comprehensive error handling and resilience strategies!
-
-**Continue to:** [Module 5: Error Handling →](./integration-patterns-05-error-handling.md)
-
-Or explore:
-
-- [Complete Example: XML Order Webhook](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
-- [Versori Webhook Response Patterns](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)
-- [GraphQL Mutation Mapper API](../../../02-CORE-GUIDES/api-reference/modules/api-reference-04-graphql-mapping.md)
-
----
-
-## Additional Resources
-
-- [Versori Webhook Documentation](https://docs.versori.com/)
-- [XMLParserService API Reference](../../../02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-04-xml-parser.md)
-- [GraphQL Mutation Mapper Guide](../../../02-CORE-GUIDES/api-reference/modules/api-reference-04-graphql-mapping.md)
-- [Webhook Security Best Practices](../../../02-CORE-GUIDES/webhook-validation/examples/webhook-validation-readme.md)
-
----
-
-[← Back to Index](../integration-patterns-readme.md) | [Previous: Delta Sync →](./integration-patterns-03-delta-sync.md) | [Next: Error Handling →](./integration-patterns-05-error-handling.md)
+# Module 4: Webhook Patterns
+
+> **Learning Objective:** Master webhook integration patterns for event-driven architectures, including request parsing, response formatting, and error handling.
+>
+> **Level:** Intermediate
+
+## Table of Contents
+
+1. [What are Webhooks?](#what-are-webhooks)
+2. [Webhook Types and Patterns](#webhook-types-and-patterns)
+3. [SDK Webhook Components](#sdk-webhook-components)
+4. [Pattern 1: JSON Request/Response](#pattern-1-json-requestresponse)
+5. [Pattern 2: XML Request/Response](#pattern-2-xml-requestresponse)
+6. `Pattern 3: Mixed Format (XML→JSON)`
+7. [Versori Webhook Response Handling](#versori-webhook-response-handling)
+8. [Webhook Security](#webhook-security)
+9. [Error Handling and Retry Logic](#error-handling-and-retry-logic)
+10. [Complete Examples](#complete-examples)
+11. [Next Steps](#next-steps)
+
+---
+
+## What are Webhooks?
+
+**Webhooks** are HTTP endpoints that receive event notifications from external systems in real-time.
+
+### Webhook Flow
+
+```
+External System         Your Webhook           Fluent Commerce
+     │                       │                        │
+     │  ① Event occurs       │                        │
+     │  (order placed)       │                        │
+     │                       │                        │
+     │  ② HTTP POST ────────>│                        │
+     │     Payload (XML/JSON)│                        │
+     │                       │                        │
+     │                       │  ③ Parse payload       │
+     │                       │  ④ Transform data      │
+     │                       │                        │
+     │                       │  ⑤ GraphQL mutation ──>│
+     │                       │                        │
+     │                       │<── ⑥ Response          │
+     │                       │                        │
+     │<── ⑦ 200 OK          │                        │
+     │     Success message   │                        │
+```
+
+### Key Characteristics
+
+| Characteristic   | Description                  | Example                |
+| ---------------- | ---------------------------- | ---------------------- |
+| **Push-Based**   | External system initiates    | SFCC pushes order      |
+| **Event-Driven** | Triggered by specific events | Order created, shipped |
+| **Synchronous**  | Caller waits for response    | Return 200 OK or 500   |
+| **Real-Time**    | Immediate processing         | < 5 second response    |
+
+---
+
+## Webhook Types and Patterns
+
+### By Input Format
+
+| Type          | Content-Type                        | Example Source  | SDK Parser         |
+| ------------- | ----------------------------------- | --------------- | ------------------ |
+| **JSON**      | `application/json`                  | Shopify, Stripe | Native JSON.parse  |
+| **XML**       | `application/xml`                   | SFCC, Radial    | `XMLParserService` |
+| **Form Data** | `application/x-www-form-urlencoded` | Older systems  | URLSearchParams    |
+| **Multipart** | `multipart/form-data`               | File uploads    | Not supported      |
+
+### By Response Format
+
+| Type           | Content-Type       | Use Case        | Pattern         |
+| -------------- | ------------------ | --------------- | --------------- |
+| **JSON**       | `application/json` | API responses   | Default         |
+| **XML**        | `application/xml`  | SOAP/EDI     | Custom Response |
+| **HTML**       | `text/html`        | Browser display | Custom Response |
+| **Plain Text** | `text/plain`       | Simple status   | Custom Response |
+
+### By Processing Pattern
+
+| Pattern             | Latency            | Complexity | Example                        |
+| ------------------- | ------------------ | ---------- | ------------------------------ |
+| **Immediate**       | < 2 sec            | Low        | Status update                  |
+| **Transformation**  | 2-5 sec            | Medium     | XML → GraphQL                  |
+| **Lookup & Create** | 3-10 sec           | High       | Customer lookup + order create |
+| **Async**           | Return immediately | High       | Queue for later processing     |
+
+---
+
+## SDK Webhook Components
+
+### Component 1: `XMLParserService`
+
+**Purpose**: Parse XML payloads (SFCC, Radial, SOAP)
+
+```typescript
+import { XMLParserService } from '@fluentcommerce/fc-connect-sdk';
+
+const parser = new XMLParserService({
+  ignoreAttributes: false, // Keep XML attributes
+  attributeNamePrefix: '@', // Prefix for attributes
+  textNodeName: '_', // Text content key
+  parseAttributeValue: true, // Parse attribute values
+});
+
+// Parse XML string
+const xmlData = await parser.parse(xmlString);
+
+// Parse with path resolution
+const value = await parser.parseWithPath(xmlString, 'order.items.item[0].sku');
+```
+
+### Component 2: `GraphQLMutationMapper`
+
+**Purpose**: Transform XML/JSON to GraphQL mutations
+
+```typescript
+import { GraphQLMutationMapper } from '@fluentcommerce/fc-connect-sdk';
+
+const mapper = new GraphQLMutationMapper(mappingConfig, logger, { fluentClient: client });
+
+// Process with nodes (extract nested/escaped XML)
+const result = await mapper.mapWithNodes(sourceData, customResolvers, context);
+
+// Check success (errors are returned, not thrown)
+if (!result.success) {
+  console.error('Mapping failed:', result.errors);
+  return;
+}
+
+// Execute (query is auto-generated in result)
+const data = await client.graphql({ 
+  query: result.query, 
+  variables: result.variables  // ✅ Use variables (wrapped if fields pattern)
+});
+```
+
+**Key features**:
+
+- **Nodes**: Extract nested XML before mapping
+- **Path Resolution**: Navigate complex XML/JSON structures
+- **Custom Resolvers**: Apply business logic (async supported)
+- **Validation**: Required fields and types
+
+### Component 3: `createClient()`
+
+**Purpose**: Create authenticated Fluent client
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+// Versori platform
+const client = await createClient({
+  connection: connections.fluent_commerce,
+  logger: log,
+});
+
+// Standalone
+const client = await createClient({
+  config: {
+    baseUrl: 'https://api.fluentcommerce.com',
+    clientId: process.env.FLUENT_CLIENT_ID,
+    clientSecret: process.env.FLUENT_CLIENT_SECRET,
+    retailerId: process.env.FLUENT_RETAILER_ID,
+  },
+});
+```
+
+### Component 4: Versori Webhook Utilities
+
+**Available in Versori platform**:
+
+```typescript
+import { webhook, fn, http } from '@versori/run';
+
+// Create webhook endpoint
+export const orderWebhook = webhook('order-create', async ctx => {
+  const orderData = ctx.request.body;
+  // Process order
+  return { success: true };
+});
+
+// With custom response handlers
+export const xmlWebhook = webhook('xml-endpoint', {
+  response: {
+    mode: 'sync',
+    onSuccess: ctx =>
+      new Response(ctx.data, {
+        status: 200,
+        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+      }),
+  },
+}).then(
+  fn('process', async ctx => {
+    // Process data
+    return '<response>Success</response>';
+  })
+);
+```
+
+---
+
+## Pattern 1: JSON Request/Response
+
+### Use Case
+
+**Modern APIs** (Shopify, Stripe, custom REST APIs) sending JSON webhooks.
+
+### Implementation
+
+```typescript
+/**
+ * JSON Webhook: Shopify Order → Fluent Order
+ *
+ * Input: application/json
+ * Output: application/json
+ */
+
+import { createClient, UniversalMapper } from '@fluentcommerce/fc-connect-sdk';
+
+export default async function shopifyOrderWebhook(activation: any, log: any, connections: any) {
+  try {
+    // Step 1: Extract JSON payload (Versori auto-parses)
+    const shopifyOrder = activation.body;
+
+    log.info('Received Shopify order', {
+      orderId: shopifyOrder.id,
+      orderNumber: shopifyOrder.order_number,
+    });
+
+    // Step 2: Validate payload
+    if (!shopifyOrder.id || !shopifyOrder.line_items) {
+      throw new Error('Invalid Shopify order payload');
+    }
+
+    // Step 3: Create Fluent client
+    const client = await createClient({
+      connection: connections.fluent_commerce,
+      logger: log,
+    });
+
+    // Step 4: Map Shopify → Fluent
+    const mapper = new UniversalMapper(
+      {
+        fields: {
+          ref: { source: 'order_number', required: true },
+          type: { value: 'HD' },
+          totalPrice: { source: 'total_price', resolver: 'sdk.parseFloat' },
+          currency: { source: 'currency' },
+          'retailer.id': { value: '2' },
+          'customer.id': { resolver: 'custom.lookupCustomer' },
+          'items[]': {
+            source: 'line_items',
+            fields: {
+              ref: { source: '$.id', resolver: 'sdk.toString' },
+              productRef: { source: '$.sku', required: true },
+              quantity: { source: '$.quantity', resolver: 'sdk.parseInt' },
+              price: { source: '$.price', resolver: 'sdk.parseFloat' },
+              currency: { source: '^.currency' },
+            },
+          },
+        },
+      },
+      {
+        customResolvers: {
+          'custom.lookupCustomer': async (value, data, config, helpers) => {
+            const email = data.customer?.email;
+            if (!email) return null;
+
+            // Query for customer
+            const result = await helpers.fluentClient.graphql({
+              query: `query GetCustomer($email: String) {
+              customers(primaryEmail: $email, first: 1) {
+                edges { node { id } }
+              }
+            }`,
+              variables: { email },
+            });
+
+            return result?.customers?.edges?.[0]?.node?.id || null;
+          },
+        },
+      }
+    );
+
+    // map() returns GraphQLPayload { query, variables } - ready to execute!
+    const mapResult = await mapper.map(shopifyOrder, {
+      fluentClient: client,
+    });
+
+    // Step 5: Create order in Fluent (mapResult already has query + variables)
+    const order = await client.graphql(mapResult);
+
+    log.info('Order created in Fluent', {
+      fluentOrderId: order.id,
+      fluentOrderRef: order.ref,
+    });
+
+    // Step 6: Return JSON response
+    return {
+      status: 200,
+      body: {
+        success: true,
+        shopifyOrderId: shopifyOrder.id,
+        fluentOrderId: order.id,
+        fluentOrderRef: order.ref,
+      },
+    };
+  } catch (error: any) {
+    log.error('Shopify webhook failed', error);
+
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: error.message,
+      },
+    };
+  }
+}
+```
+
+### Example Payload
+
+**Input** (Shopify webhook):
+
+```json
+{
+  "id": 12345678,
+  "order_number": "SO-1001",
+  "total_price": "159.98",
+  "currency": "USD",
+  "customer": {
+    "email": "customer@example.com"
+  },
+  "line_items": [
+    {
+      "id": 111,
+      "sku": "SKU-001",
+      "quantity": 2,
+      "price": "79.99"
+    }
+  ]
+}
+```
+
+**Output**:
+
+```json
+{
+  "success": true,
+  "shopifyOrderId": 12345678,
+  "fluentOrderId": "1234",
+  "fluentOrderRef": "SO-1001"
+}
+```
+
+---
+
+## Pattern 2: XML Request/Response
+
+### Use Case
+
+**Older systems** (SFCC, Radial, SOAP) sending XML webhooks and expecting XML responses.
+
+### Implementation
+
+See complete implementation: [XML Order Ingestion](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
+
+### Quick Example
+
+```typescript
+/**
+ * XML Webhook: SFCC Order → Fluent Order → XML Response
+ *
+ * Input: application/xml
+ * Output: application/xml
+ */
+
+import {
+  createClient,
+  GraphQLMutationMapper,
+  XMLParserService,
+} from '@fluentcommerce/fc-connect-sdk';
+import { webhook, fn } from '@versori/run';
+import { XMLBuilder } from 'fast-xml-parser';
+
+export const sfccOrderWebhook = webhook('sfcc-order', {
+  response: {
+    mode: 'sync',
+    // CRITICAL: Custom response handler for XML (not JSON)
+    onSuccess: ctx =>
+      new Response(ctx.data, {
+        status: 200,
+        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+      }),
+    onError: ctx =>
+      new Response(ctx.data, {
+        status: 500,
+        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+      }),
+  },
+})
+  .then(
+    fn('process-order', async ctx => {
+      const { body } = ctx.request;
+      const { log, connections } = ctx;
+
+      try {
+        // Parse XML (Versori pre-parses, but you can re-parse if needed)
+        const parser = new XMLParserService();
+        const orderData = typeof body === 'string' ? await parser.parse(body) : body;
+
+        // Create client
+        const client = await createClient({
+          connection: connections.fluent_commerce,
+          logger: log,
+        });
+
+        // Map XML → GraphQL
+        const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
+        const result = await mapper.mapWithNodes(orderData, customResolvers, {
+          fluentClient: client,
+        });
+
+        if (!result.success) {
+          throw new Error(`Mapping failed: ${result.errors?.join(', ')}`);
+        }
+
+        // Execute mutation (query is auto-generated in result)
+        const order = await client.graphql({
+          query: result.query,
+          variables: result.variables,  // ✅ Use variables (wrapped if fields pattern)
+        });
+
+        // Build XML response
+        const builder = new XMLBuilder({
+          ignoreAttributes: false,
+          attributeNamePrefix: '@',
+        });
+
+        const xmlResponse = builder.build({
+          OrderResponse: {
+            '@status': 'success',
+            OrderId: order.id,
+            OrderRef: order.ref,
+            Message: 'Order created successfully',
+          },
+        });
+
+        return `<?xml version="1.0" encoding="UTF-8"?>\n${xmlResponse}`;
+      } catch (error: any) {
+        log.error('SFCC order processing failed', error);
+
+        // Build XML error response
+        const builder = new XMLBuilder({ ignoreAttributes: false });
+        const xmlError = builder.build({
+          OrderResponse: {
+            '@status': 'error',
+            ErrorMessage: error.message,
+          },
+        });
+
+        throw new Error(`<?xml version="1.0" encoding="UTF-8"?>\n${xmlError}`);
+      }
+    })
+  )
+  .catch(({ data }) => {
+    // Return error XML (already formatted in catch block)
+    return data;
+  });
+```
+
+**Why custom response handler?**
+
+Versori's default behavior JSON-encodes all responses. For XML, you must use `Response` objects with proper Content-Type.
+
+See: [Versori Webhook Response Patterns](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)
+
+---
+
+## Pattern 3: Mixed Format (XML→JSON)
+
+### Use Case
+
+**Older system input, modern output**: Receive XML webhook, return JSON response.
+
+### Implementation
+
+```typescript
+/**
+ * Mixed Format Webhook: XML Input → JSON Output
+ *
+ * Input: application/xml
+ * Output: application/json
+ */
+
+import {
+  createClient,
+  GraphQLMutationMapper,
+  XMLParserService,
+} from '@fluentcommerce/fc-connect-sdk';
+
+export default async function mixedFormatWebhook(activation: any, log: any, connections: any) {
+  try {
+    // Parse XML input
+    const parser = new XMLParserService();
+    const xmlData =
+      typeof activation.body === 'string' ? await parser.parse(activation.body) : activation.body;
+
+    log.info('Parsed XML payload', { rootKeys: Object.keys(xmlData) });
+
+    // Create client
+    const client = await createClient({
+      connection: connections.fluent_commerce,
+      logger: log,
+    });
+
+    // Map XML → GraphQL
+    const mapper = new GraphQLMutationMapper(mappingConfig, log, { fluentClient: client });
+    const result = await mapper.mapWithNodes(xmlData, customResolvers, {
+      fluentClient: client,
+    });
+
+    if (!result.success) {
+      throw new Error(`Mapping failed: ${result.errors?.join(', ')}`);
+    }
+
+    // Execute mutation (query is auto-generated in result)
+    const order = await client.graphql({
+      query: result.query,
+      variables: result.variables,  // ✅ Use variables (wrapped if fields pattern)
+    });
+
+    // Return JSON response (default Versori behavior)
+    return {
+      status: 200,
+      body: {
+        success: true,
+        orderId: order.id,
+        orderRef: order.ref,
+        message: 'Order created successfully',
+      },
+    };
+  } catch (error: any) {
+    log.error('Webhook processing failed', error);
+
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: error.message,
+      },
+    };
+  }
+}
+```
+
+---
+
+## Versori Webhook Response Handling
+
+### Critical Pattern: Non-JSON Responses
+
+**Problem**: Versori default handlers JSON-encode all responses.
+
+**Solution**: Use custom `onSuccess`/`onError` handlers with `Response` objects.
+
+### XML Response Pattern
+
+```typescript
+export const xmlEndpoint = webhook('xml', {
+  response: {
+    mode: 'sync',
+    onSuccess: ctx =>
+      new Response(ctx.data, {
+        status: 200,
+        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+      }),
+    onError: ctx =>
+      new Response(ctx.data, {
+        status: 500,
+        headers: { 'Content-Type': 'application/xml; charset=utf-8' },
+      }),
+  },
+})
+  .then(fn('gen', () => '<?xml version="1.0"?><response>Success</response>'))
+  .catch(({ data }) => '<error>Failed</error>');
+```
+
+### HTML Response Pattern
+
+```typescript
+export const htmlEndpoint = webhook('html', {
+  response: {
+    mode: 'sync',
+    onSuccess: ctx =>
+      new Response(ctx.data, {
+        status: 200,
+        headers: { 'Content-Type': 'text/html; charset=utf-8' },
+      }),
+  },
+}).then(fn('gen', () => '<!DOCTYPE html><html><body>OK</body></html>'));
+```
+
+### CSV Download Pattern
+
+```typescript
+export const csvEndpoint = webhook('csv', {
+  response: {
+    mode: 'sync',
+    onSuccess: ctx =>
+      new Response(ctx.data, {
+        status: 200,
+        headers: {
+          'Content-Type': 'text/csv; charset=utf-8',
+          'Content-Disposition': 'attachment; filename="data.csv"',
+        },
+      }),
+  },
+}).then(fn('gen', () => 'ID,Name,Value\n1,Item,100'));
+```
+
+**Complete guide**: [Versori Webhook Response Patterns](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)
+
+---
+
+## Webhook Security
+
+### Pattern 1: Fluent Commerce Webhook Validation
+
+⚠️ **CRITICAL LIMITATION:** The SDK's `validateWebhook()` method **ONLY works with Fluent Commerce Rubix webhooks**. Do not use for Shopify, GitHub, Stripe, or other third-party webhooks. See Pattern 3 for those systems.
+
+**Use FluentClient.validateWebhook()** for cryptographic signature validation of **Fluent Commerce webhooks only**.
+
+The SDK provides built-in webhook validation using RSA-based algorithms (SHA512withRSA, MD5withRSA).
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+/**
+ * SDK Webhook Validation - Fluent Commerce Only
+ *
+ * Supports: SHA512withRSA (fluent-signature), MD5withRSA (flex.signature)
+ * Does NOT support: Shopify, GitHub, Stripe, or other third-party webhooks
+ */
+export default async function secureFluentWebhook(activation: any, log: any, connections: any) {
+  try {
+    // Create client with public key
+    const client = await createClient({
+      connection: connections.fluent_commerce,
+      logger: log,
+      publicKey: process.env.FLUENT_WEBHOOK_PUBLIC_KEY, // Required for webhook validation
+    });
+
+    // Get raw body (CRITICAL: Must be raw string, not parsed JSON)
+    const rawBody = activation.rawBody || JSON.stringify(activation.body);
+    const payload = typeof activation.body === 'string' ? JSON.parse(activation.body) : activation.body;
+
+    // Extract signature from Fluent Commerce headers
+    const signature = activation.headers['fluent-signature'] || activation.headers['flex.signature'];
+
+    if (!signature) {
+      log.error('Missing Fluent Commerce signature header');
+      return { status: 401, body: { error: 'Unauthorized' } };
+    }
+
+    // Validate webhook signature using SDK (Fluent Commerce only)
+    const isValid = await client.validateWebhook(payload, signature, rawBody);
+
+    if (!isValid) {
+      log.error('Invalid Fluent Commerce webhook signature');
+      return { status: 401, body: { error: 'Unauthorized' } };
+    }
+
+    log.info('Fluent Commerce webhook signature validated successfully');
+
+    // Process webhook
+    const result = await processFluentWebhook(payload, client, log);
+
+    return {
+      status: 200,
+      body: {
+        success: true,
+        ...result,
+      },
+    };
+  } catch (error: any) {
+    log.error('Webhook validation or processing failed', error);
+
+    return {
+      status: 500,
+      body: {
+        success: false,
+        error: error.message,
+      },
+    };
+  }
+}
+```
+
+### Fluent Commerce Signature Headers
+
+The SDK automatically detects the signature algorithm from headers:
+
+| Header | Algorithm | Status |
+|--------|-----------|--------|
+| `fluent-signature` | SHA512withRSA | **Recommended** |
+| `x-fluent-signature` | SHA512withRSA | Supported |
+| `flex.signature` | MD5withRSA | **Older algorithm** |
+| `flex-signature` | MD5withRSA | Supported |
+
+```typescript
+// Auto-detection (recommended)
+const signature = headers['fluent-signature'] || headers['flex.signature'];
+const isValid = await client.validateWebhook(payload, signature, rawBody);
+```
+
+### Pattern 2: IP Allowlist (All Webhook Types)
+
+**Restrict webhook sources** to known IP addresses - works for Fluent Commerce, Shopify, GitHub, Stripe, etc.
+
+```typescript
+const ALLOWED_IPS = ['192.168.1.1', '10.0.0.0/8'];
+
+function isIPAllowed(ip: string): boolean {
+  return ALLOWED_IPS.some(allowed => {
+    if (allowed.includes('/')) {
+      // CIDR range check (use ip-cidr library)
+      return true; // Simplified
+    }
+    return ip === allowed;
+  });
+}
+
+// Usage
+export default async function ipRestrictedWebhook(activation: any, log: any) {
+  const clientIP = activation.headers['x-forwarded-for'] || activation.ip;
+
+  if (!isIPAllowed(clientIP)) {
+    log.warn('Blocked request from unauthorized IP', { ip: clientIP });
+    return { status: 403, body: { error: 'Forbidden' } };
+  }
+
+  // Process webhook
+}
+```
+
+### Pattern 3: Third-Party Webhook Validation (Shopify, GitHub, Stripe)
+
+⚠️ **REQUIRED FOR THIRD-PARTY WEBHOOKS:** The SDK's `validateWebhook()` does NOT support HMAC algorithms used by Shopify, GitHub, Stripe. You must implement manual HMAC validation for these systems.
+
+#### Shopify Webhook Validation (HMAC-SHA256, base64)
+
+```typescript
+import crypto from 'crypto';
+
+/**
+ * Validate Shopify webhook signature
+ * Algorithm: HMAC-SHA256 with base64 encoding
+ */
+function validateShopifyWebhook(rawBody: string, signature: string, secret: string): boolean {
+  const hash = crypto
+    .createHmac('sha256', secret)
+    .update(rawBody, 'utf8')
+    .digest('base64');
+
+  return hash === signature;
+}
+
+// Usage
+export default async function shopifyWebhook(activation: any, log: any) {
+  const rawBody = activation.rawBody || JSON.stringify(activation.body);
+  const signature = activation.headers['x-shopify-hmac-sha256'];
+  const secret = process.env.SHOPIFY_WEBHOOK_SECRET!;
+
+  if (!validateShopifyWebhook(rawBody, signature, secret)) {
+    log.error('Invalid Shopify webhook signature');
+    return { status: 401, body: { error: 'Unauthorized' } };
+  }
+
+  // Process webhook
+  const order = await processShopifyOrder(activation.body);
+  return { status: 200, body: { success: true, orderId: order.id } };
+}
+```
+
+#### GitHub Webhook Validation (HMAC-SHA256, hex with prefix)
+
+```typescript
+import crypto from 'crypto';
+
+/**
+ * Validate GitHub webhook signature
+ * Algorithm: HMAC-SHA256 with hex encoding and sha256= prefix
+ */
+function validateGitHubWebhook(rawBody: string, signature: string, secret: string): boolean {
+  const hash = crypto
+    .createHmac('sha256', secret)
+    .update(rawBody, 'utf8')
+    .digest('hex');
+
+  const expected = `sha256=${hash}`;
+  return expected === signature;
+}
+
+// Usage
+export default async function githubWebhook(activation: any, log: any) {
+  const rawBody = activation.rawBody || JSON.stringify(activation.body);
+  const signature = activation.headers['x-hub-signature-256'];
+  const secret = process.env.GITHUB_WEBHOOK_SECRET!;
+
+  if (!validateGitHubWebhook(rawBody, signature, secret)) {
+    log.error('Invalid GitHub webhook signature');
+    return { status: 401, body: { error: 'Unauthorized' } };
+  }
+
+  // Process webhook
+  const result = await processGitHubEvent(activation.body);
+  return { status: 200, body: { success: true } };
+}
+```
+
+#### Stripe Webhook Validation (HMAC-SHA256 with timestamp)
+
+```typescript
+import crypto from 'crypto';
+
+/**
+ * Validate Stripe webhook signature
+ * Algorithm: HMAC-SHA256 with timestamp verification to prevent replay attacks
+ */
+function validateStripeWebhook(
+  rawBody: string,
+  signature: string,
+  secret: string,
+  tolerance: number = 300 // 5 minutes
+): boolean {
+  // Parse signature header: t=timestamp,v1=signature
+  const parts = signature.split(',');
+  const timestamp = parts.find(p => p.startsWith('t='))?.split('=')[1];
+  const sig = parts.find(p => p.startsWith('v1='))?.split('=')[1];
+
+  if (!timestamp || !sig) return false;
+
+  // Check timestamp tolerance (prevent replay attacks)
+  const now = Math.floor(Date.now() / 1000);
+  if (Math.abs(now - parseInt(timestamp)) > tolerance) {
+    return false;
+  }
+
+  // Verify signature
+  const payload = `${timestamp}.${rawBody}`;
+  const hash = crypto
+    .createHmac('sha256', secret)
+    .update(payload, 'utf8')
+    .digest('hex');
+
+  return hash === sig;
+}
+
+// Usage
+export default async function stripeWebhook(activation: any, log: any) {
+  const rawBody = activation.rawBody || JSON.stringify(activation.body);
+  const signature = activation.headers['stripe-signature'];
+  const secret = process.env.STRIPE_WEBHOOK_SECRET!;
+
+  if (!validateStripeWebhook(rawBody, signature, secret)) {
+    log.error('Invalid Stripe webhook signature');
+    return { status: 401, body: { error: 'Unauthorized' } };
+  }
+
+  // Process webhook
+  const result = await processStripeEvent(activation.body);
+  return { status: 200, body: { success: true } };
+}
+```
+
+#### Third-Party Webhook Algorithms
+
+| Provider | Algorithm | Encoding | Header | Notes |
+|----------|-----------|----------|--------|-------|
+| **Shopify** | HMAC-SHA256 | base64 | `x-shopify-hmac-sha256` | Simple HMAC |
+| **GitHub** | HMAC-SHA256 | hex | `x-hub-signature-256` | Prefixed with `sha256=` |
+| **Stripe** | HMAC-SHA256 | hex | `stripe-signature` | Includes timestamp (replay protection) |
+| **PayPal** | HMAC-SHA256 | base64 | `paypal-transmission-sig` | Multiple verification params |
+
+### Error Handling for Validation
+
+```typescript
+// Fluent Commerce webhook validation error handling
+try {
+  const isValid = await client.validateWebhook(payload, signature, rawBody);
+
+  if (!isValid) {
+    log.error('Fluent Commerce webhook signature validation failed', {
+      header: signature ? 'present' : 'missing',
+      algorithm: signature?.includes('fluent-signature') ? 'SHA512withRSA' : 'MD5withRSA',
+    });
+
+    return {
+      status: 401,
+      body: {
+        error: 'Unauthorized',
+        message: 'Invalid webhook signature',
+      },
+    };
+  }
+
+  // Process webhook
+} catch (error: any) {
+  log.error('Webhook validation error', error);
+
+  return {
+    status: 500,
+    body: {
+      error: 'Internal error',
+      message: error.message,
+    },
+  };
+}
+
+// Third-party webhook validation error handling (Shopify example)
+try {
+  const signature = headers['x-shopify-hmac-sha256'];
+  const secret = process.env.SHOPIFY_WEBHOOK_SECRET;
+
+  if (!signature || !secret) {
+    log.error('Missing Shopify webhook credentials');
+    return { status: 401, body: { error: 'Unauthorized' } };
+  }
+
+  const isValid = validateShopifyWebhook(rawBody, signature, secret);
+
+  if (!isValid) {
+    log.error('Shopify webhook signature validation failed');
+    return { status: 401, body: { error: 'Unauthorized' } };
+  }
+
+  // Process webhook
+} catch (error: any) {
+  log.error('Shopify webhook validation error', error);
+  return { status: 500, body: { error: 'Internal error' } };
+}
+```
+
+
+### Pattern 5: API Key Authentication
+
+**Require API key** in headers (alternative to signature validation).
+
+```typescript
+export default async function apiKeyWebhook(activation: any, log: any) {
+  const apiKey = activation.headers['x-api-key'];
+  const expectedKey = process.env.WEBHOOK_API_KEY!;
+
+  if (!apiKey || apiKey !== expectedKey) {
+    log.error('Missing or invalid API key');
+    return { status: 401, body: { error: 'Unauthorized' } };
+  }
+
+  // Process webhook
+}
+```
+
+---
+
+## Error Handling and Retry Logic
+
+### HTTP Status Codes
+
+| Status  | Meaning                    | Retry? | Example                   |
+| ------- | -------------------------- | ------ | ------------------------- |
+| **200** | Success                    | No     | Order created             |
+| **400** | Bad Request (client error) | No     | Invalid payload           |
+| **401** | Unauthorized               | No     | Missing/invalid signature |
+| **422** | Unprocessable Entity       | No     | Validation failed         |
+| **429** | Rate Limit                 | Yes    | Too many requests         |
+| **500** | Server Error               | Yes    | Fluent API down           |
+| **503** | Service Unavailable        | Yes    | Temporary outage          |
+
+### Error Response Pattern
+
+```typescript
+try {
+  // Process webhook
+
+  return {
+    status: 200,
+    body: {
+      success: true,
+      orderId: order.id,
+    },
+  };
+} catch (error: any) {
+  // Categorize error
+  if (error.message.includes('required field')) {
+    // Validation error - don't retry
+    return {
+      status: 400,
+      body: {
+        success: false,
+        error: 'Validation failed',
+        details: error.message,
+      },
+    };
+  }
+
+  if (error.message.includes('rate limit')) {
+    // Rate limit - retry after delay
+    return {
+      status: 429,
+      body: {
+        success: false,
+        error: 'Rate limit exceeded',
+        retryAfter: 60,
+      },
+    };
+  }
+
+  // Unknown error - retryable
+  return {
+    status: 500,
+    body: {
+      success: false,
+      error: 'Internal server error',
+      retryable: true,
+    },
+  };
+}
+```
+
+### Idempotency Pattern
+
+**Prevent duplicate processing** of same webhook.
+
+```typescript
+import { StateService, VersoriKVAdapter } from '@fluentcommerce/fc-connect-sdk';
+
+export default async function idempotentWebhook(activation: any, log: any) {
+  const kvAdapter = new VersoriKVAdapter(openKv());
+  const stateService = new StateService(logger);
+
+  // Use webhook ID or order ID as idempotency key
+  const idempotencyKey = `webhook:${activation.body.id}`;
+
+  // Check if already processed
+  const processed = await stateService.getState(idempotencyKey);
+
+  if (processed) {
+    log.info('Webhook already processed', { id: activation.body.id });
+    return {
+      status: 200,
+      body: {
+        success: true,
+        message: 'Already processed',
+        orderId: processed.orderId,
+      },
+    };
+  }
+
+  // Process webhook
+  const order = await processOrder(activation.body);
+
+  // Mark as processed
+  await stateService.setState(idempotencyKey, {
+    orderId: order.id,
+    processedAt: new Date().toISOString(),
+  });
+
+  return {
+    status: 200,
+    body: {
+      success: true,
+      orderId: order.id,
+    },
+  };
+}
+```
+
+---
+
+## Complete Examples
+
+### Example 1: Shopify Order Webhook (JSON)
+
+Complete production-ready Shopify integration with:
+
+- JSON parsing
+- Customer lookup/create
+- Order creation
+- Error handling
+
+See: [Common Patterns](../examples/common-patterns.ts)
+
+### Example 2: SFCC Order Webhook (XML)
+
+Complete production-ready SFCC integration with:
+
+- XML parsing with nodes
+- GraphQL mutation mapping
+- Custom resolvers
+- XML response formatting
+
+See: [XML Order Ingestion](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
+
+### Example 3: Inventory Webhook (JSON)
+
+Simple inventory update webhook:
+
+- Single SKU update
+- Direct GraphQL mutation
+- Fast response (< 2 sec)
+
+```typescript
+import { createClient } from '@fluentcommerce/fc-connect-sdk';
+
+export default async function inventoryWebhook(activation: any, log: any, connections: any) {
+  const { sku, location, quantity } = activation.body;
+
+  const client = await createClient({
+    connection: connections.fluent_commerce,
+    logger: log,
+  });
+
+  const result = await client.graphql({
+    query: `
+      mutation UpdateInventory($input: UpdateInventoryQuantityInput!) {
+        updateInventoryQuantity(input: $input) {
+          id
+          ref
+          onHand
+        }
+      }
+    `,
+    variables: {
+      input: {
+        ref: `${sku}-${location}`,
+        onHand: quantity,
+      },
+    },
+  });
+
+  return {
+    status: 200,
+    body: {
+      success: true,
+      inventoryId: result.id,
+      newQuantity: result.onHand,
+    },
+  };
+}
+```
+
+---
+
+## Next Steps
+
+Now that you understand webhook patterns, you're ready to learn comprehensive error handling and resilience strategies!
+
+**Continue to:** [Module 5: Error Handling →](./integration-patterns-05-error-handling.md)
+
+Or explore:
+
+- [Complete Example: XML Order Webhook](../../../01-TEMPLATES/versori/webhooks/template-webhook-xml-order-ingestion.md)
+- [Versori Webhook Response Patterns](../../../04-REFERENCE/platforms/versori/modules/platforms-versori-04-workflows.md#critical-non-json-response-handlers-xml-html-csv)
+- [GraphQL Mutation Mapper API](../../../02-CORE-GUIDES/api-reference/modules/api-reference-04-graphql-mapping.md)
+
+---
+
+## Additional Resources
+
+- [Versori Webhook Documentation](https://docs.versori.com/)
+- [XMLParserService API Reference](../../../02-CORE-GUIDES/parsers/modules/02-core-guides-parsers-04-xml-parser.md)
+- [GraphQL Mutation Mapper Guide](../../../02-CORE-GUIDES/api-reference/modules/api-reference-04-graphql-mapping.md)
+- [Webhook Security Best Practices](../../../02-CORE-GUIDES/webhook-validation/examples/webhook-validation-readme.md)
+
+---
+
+[← Back to Index](../integration-patterns-readme.md) | [Previous: Delta Sync →](./integration-patterns-03-delta-sync.md) | [Next: Error Handling →](./integration-patterns-05-error-handling.md)