Order Failed Webhook - Operation Type Specification

This page provides detailed documentation for the updated order:failed webhook that uses an operation-type oriented approach, specifically designed for the Naveo-SOM (Salesforce Order Management) integration.

Overview

As Naveo APIs are asynchronous and don't indicate to Salesforce(SOM) if an operation was successful or not (only that the request was successfully received), webhook event notifications are sent by Naveo to SOM with operation failure details when operations requested by SOM fail in Naveo.

The webhook has been updated to use an operation-type oriented approach instead of the previous failure-type oriented approach. This provides better clarity on what specific operation failed.

Operation Types

The webhook now includes operation_type as the primary key to indicate what operation failed:

Operation Type	Description	Use Case
`order_create`	Order creation failed	When SOM sends an order to Naveo but creation fails
`order_status_update`	Order status update failed	When SOM requests a status change (e.g., to `cancelled` or `retrieving`) but it fails
`order_validation`	Order validation failed	When incoming order data fails validation
`order_payment`	Payment processing failed	When payment operations fail
`place_resolution`	Place ID resolution failed	When place_external_id cannot be resolved to internal place_id

Webhook Payload Structure

Base Structure

{
  "event_type": "order:failed",
  "event_id": "evt-{operation}-{unique_id}",
  "timestamp": "2023-12-01T10:30:00.000Z",
  "data": {
    "channel_id": "salesforce-channel-123",
    "order_number": "SF-ORD-789",
    "operation_type": "{operation_type}",
    "error_count": 1,
    "metadata": {
      "timestamp": "2023-12-01T10:30:00.000Z",
      "errors": ["List of error messages"],
      "error_code": "SPECIFIC_ERROR_CODE",
      "processor": "component-that-failed",
      // Operation-specific fields...
      "failure_type": "processing", // Included for backward compatibility
      "order_data": {
        "order_number": "SF-ORD-789",
        "channel_id": "salesforce-channel-123"
        // Additional order context...
      }
    }
  }
}

Operation-Specific Documentation

order_status_update

Used when SOM requests a status change but the transition is invalid or fails.

Key Fields:

requested_status - The status that SOM requested
current_status - The current status of the order
valid_transitions - Array of valid status transitions from current status
error_code - Specific error code (e.g., "INVALID_STATUS_TRANSITION")
updated_by - Who/what requested the status change

Common Scenarios:

Cancelled Status Request: SOM requests to cancel an order that cannot be cancelled
Retrieving Status Request: SOM requests to set status to "retrieving" (courier on the way) but order isn't ready

Example - Invalid Cancellation:

{
  "event_type": "order:failed", 
  "event_id": "evt-ordsta-xyz789",
  "timestamp": "2023-12-01T10:30:00.000Z",
  "data": {
    "channel_id": "salesforce-channel-123",
    "order_number": "SF-ORD-456", 
    "operation_type": "order_status_update",
    "error_count": 1,
    "metadata": {
      "errors": ["Cannot cancel order that is already shipped"],
      "error_code": "INVALID_STATUS_TRANSITION",
      "requested_status": "cancelled",
      "current_status": "shipped",
      "valid_transitions": [],
      "processor": "order-service",
      "updated_by": "som-api"
    }
  }
}

Example - Invalid Retrieving Request:

{
  "event_type": "order:failed",
  "event_id": "evt-ordsta-abc123", 
  "timestamp": "2023-12-01T10:35:00.000Z",
  "data": {
    "channel_id": "salesforce-channel-123",
    "order_number": "SF-ORD-789",
    "operation_type": "order_status_update", 
    "error_count": 1,
    "metadata": {
      "errors": ["Order must be picked before retrieving"], 
      "error_code": "INVALID_STATUS_TRANSITION",
      "requested_status": "retrieving",
      "current_status": "processing",
      "valid_transitions": ["picking", "cancelled"],
      "processor": "order-service",
      "updated_by": "som-api"
    }
  }
}

order_create

Used when order creation fails during processing.

Key Fields:

error_code - Error code (e.g., "ORDER_CREATE_FAILED", "ADAPTER_PROCESSING_ERROR")
processor - Which component failed
Additional context in order_data

Example:

{
  "event_type": "order:failed",
  "event_id": "evt-ordcre-456def",
  "timestamp": "2023-12-01T14:30:00.000Z",
  "data": {
    "channel_id": "salesforce-channel-123",
    "order_number": "SF-ORD-003",
    "operation_type": "order_create",
    "error_count": 1,
    "metadata": {
      "errors": ["Failed to create order in internal system"],
      "error_code": "ADAPTER_PROCESSING_ERROR",
      "processor": "salesforce-adapter",
      "order_data": {
        "order_number": "SF-ORD-003",
        "channel_id": "salesforce-channel-123"
      }
    }
  }
}

order_validation

Used when incoming order data fails validation.

Key Fields:

validation_errors - Array of validation error messages
validator - Which validator detected the errors
error_code - "VALIDATION_FAILED"

Example:

{
  "event_type": "order:failed",
  "event_id": "evt-ordval-456def",
  "timestamp": "2023-12-01T12:40:00.000Z",
  "data": {
    "channel_id": "salesforce-channel-123",
    "order_number": "SF-ORD-101",
    "operation_type": "order_validation",
    "error_count": 2,
    "metadata": {
      "validation_errors": [
        "Missing required field: customer_info.name",
        "Invalid shipping_info.method: must be 'Home Delivery' or 'Click & Collect'"
      ],
      "error_code": "VALIDATION_FAILED",
      "validator": "salesforce-adapter",
      "order_data": {
        "order_number": "SF-ORD-101",
        "has_items": true,
        "channel_id": "salesforce-channel-123",
        "place_external_id": "4576"
      }
    }
  }
}

place_resolution

Used when a place_external_id cannot be resolved to an internal place_id.

Key Fields:

place_external_id - The external place ID that couldn't be resolved
error_code - "PLACE_RESOLUTION_ERROR"

Example:

{
  "event_type": "order:failed",
  "event_id": "evt-placer-789ghi",
  "timestamp": "2023-12-01T12:45:00.000Z",
  "data": {
    "channel_id": "salesforce-channel-123",
    "order_number": "SF-ORD-202",
    "operation_type": "place_resolution",
    "error_count": 1,
    "metadata": {
      "errors": ["Failed to resolve place for external_id: store-999"],
      "error_code": "PLACE_RESOLUTION_ERROR",
      "processor": "order-service",
      "place_external_id": "store-999",
      "order_data": {
        "order_number": "SF-ORD-202",
        "channel_id": "salesforce-channel-123"
      }
    }
  }
}

order_payment

Used when payment processing fails.

Key Fields:

payment_errors - Array of payment error messages
error_code - "PAYMENT_FAILED"
payment_provider - Payment provider name

Example:

{
  "event_type": "order:failed",
  "event_id": "evt-ordpay-789ghi",
  "timestamp": "2023-12-01T15:45:00.000Z",
  "data": {
    "channel_id": "salesforce-channel-123",
    "order_number": "SF-ORD-004",
    "operation_type": "order_payment",
    "error_count": 1,
    "metadata": {
      "payment_errors": ["Payment authorization failed"],
      "error_code": "PAYMENT_FAILED",
      "payment_provider": "stripe",
      "transaction_id": "txn_1234567890",
      "order_data": {
        "order_number": "SF-ORD-004",
        "channel_id": "salesforce-channel-123",
        "total_amount": 145.99,
        "currency": "GBP"
      }
    }
  }
}

Backward Compatibility

The failure_type field is still included for backward compatibility but is now optional. The primary field to use is operation_type.

Migration from Legacy Format

Legacy Format (deprecated):

{
  "failure_type": "validation", 
  "validation_errors": ["Error message"]
}

New Format (recommended):

{
  "operation_type": "order_validation",
  "validation_errors": ["Error message"],
  "failure_type": "validation"  // Still included for compatibility
}

Error Codes Reference

Error Code	Operation Type	Description
`INVALID_STATUS_TRANSITION`	order_status_update	Requested status transition is not allowed
`VALIDATION_FAILED`	order_validation	Order data failed validation
`PLACE_RESOLUTION_ERROR`	place_resolution	Cannot resolve place_external_id
`ORDER_CREATE_FAILED`	order_create	General order creation failure
`ADAPTER_PROCESSING_ERROR`	order_create	Adapter-specific processing error
`PAYMENT_FAILED`	order_payment	Payment processing failed

Integration Guidelines for SOM

Primary Field: Use operation_type to determine what operation failed
Status Updates: For order_status_update operations, check requested_status and current_status to understand what was attempted
Error Details: Always check the errors array for human-readable error descriptions
Error Codes: Use error_code for programmatic error handling
Backward Compatibility: failure_type is still available but use operation_type for new integrations

Webhook Security

All webhook payloads are signed with HMAC-SHA256. Verify the signature in the X-Webhook-Signature header before processing the payload.

See the main Webhooks documentation for signature verification details.