Webhook Validator

Overview

The Webhook Validator delegates cart validation to an external HTTP endpoint that you host. During cart validation, Omnium sends the cart to your endpoint as a POST request. Your endpoint inspects the cart and returns a validation result that can:

• approve the cart,
• reject it with one or more validation errors, and/or
• return a modified cart (for example with adjusted line items, prices, or properties) that Omnium applies back to the cart.

This makes it suitable for custom validation rules, external stock or price checks, fraud screening, or any logic that must run against the cart and lives in your own systems.

Identifier

Setup

Add a connector named webhookValidator to the Connectors section in tenant settings. The connector's host is the URL Omnium posts the cart to.

{
  "name": "webhookValidator",
  "implementations": ["IValidator"],
  "host": "https://validation.example.com/api/cart-validate",
  "bearerToken": "YOUR_API_KEY",
  "properties": [
    { "key": "IsRequestWrapperEnabled", "value": "false" },
    { "key": "IsOnlyLineItemsUpdated", "value": "false" }
  ]
}

The name must be exactly webhookValidator — that is how Omnium locates the connector for this validator.

Authentication

Omnium sets the Authorization header on every request based on the connector configuration. Use one of:

For other schemes, add headers via customHeaders instead.

Properties

Optional connector fields

Request — what your endpoint receives

Omnium sends a POST request to the connector's host with the cart as the JSON body. Field names are camelCase.

Default (no wrapper): the body is the cart object directly.

POST /api/cart-validate HTTP/1.1
Content-Type: application/json
Authorization: Bearer YOUR_API_KEY
Accept: application/json
User-Agent: OmniumOms/{version}

{
  "id": "C123456",
  "marketId": "NOR",
  "billingCurrency": "NOK",
  "status": "Draft",
  "orderForm": {
    "lineItems": [
      {
        "lineItemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "code": "SHOE-BLACK-42",
        "displayName": "Running Shoe - Black - Size 42",
        "quantity": 1,
        "placedPrice": 999.00,
        "extendedPrice": 999.00
      }
    ],
    "subTotal": 999.00,
    "total": 999.00
  }
}

The body is the full cart (OmniumCart) — the same model returned by the Cart API. The fields above are illustrative; the actual payload contains the complete cart.

With IsRequestWrapperEnabled = true: the cart is nested under cart.

{
  "cart": {
    "id": "C123456",
    "marketId": "NOR",
    "orderForm": { "lineItems": [ /* ... */ ] }
  }
}

Request headers

Plus any headers configured via customHeaders.

Response — what your endpoint must return

Return HTTP 200 with a JSON validation result:

Each entry in validationErrors / validationWarnings:

Approve the cart

Return 200 with {} or:

{
  "isValidatedSuccessful": true
}

Reject the cart

Return one or more validationErrors. A non-empty list marks the cart as invalid regardless of isValidatedSuccessful.

{
  "isValidatedSuccessful": false,
  "validationErrors": [
    {
      "message": "Item SHOE-BLACK-42 is not available for delivery to this postal code",
      "validationType": "External",
      "referenceId": "SHOE-BLACK-42"
    }
  ]
}

Modifying the cart

To change the cart, return the updated cart in value. Omnium applies it back to the cart.

{
  "isValidatedSuccessful": true,
  "value": {
    "id": "C123456",
    "orderForm": {
      "lineItems": [
        {
          "lineItemId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "code": "SHOE-BLACK-42",
          "quantity": 1,
          "placedPrice": 899.00
        }
      ]
    }
  }
}

• When IsOnlyLineItemsUpdated = true, only value.orderForm.lineItems is applied; the rest of the returned cart is ignored.
• When IsOnlyLineItemsUpdated = false (default), the full returned cart is applied.

Behavior

Omnium sends camelCase field names in the request. Field matching on the response is case-insensitive, so isValidatedSuccessful and IsValidatedSuccessful are both accepted.