Webhook Workflow Step

Overview

The Webhook workflow step calls an external HTTP endpoint with the full order as a POST request, waits for a response, and optionally updates the order with data returned from the external system. This makes it suitable for validation, enrichment, fraud checks, or any custom logic that needs to run synchronously during order processing.

Unlike Export Order which is one-way (fire and forget), this step is two-way — the external system can modify the order by returning updated fields in the response.

Identifier

Setup

There are two ways to configure the webhook endpoint: inline on the workflow step, or via a connector in tenant settings.

Option A: Inline (simplest)

Specify Host directly as a workflow step property. No connector setup needed. Use properties with KeyGroup: "RequestHeaders" to add authentication or other custom headers.

{
  "name": "WebhookWorkflowStep",
  "active": true,
  "Connector": "Webhook",
  "Properties": [
    { "Key": "Host", "Value": "https://validation.example.com/api/validate" },
    { "Key": "Authorization", "Value": "Bearer your-token", "KeyGroup": "RequestHeaders" }
  ]
}

Optionally add "StopOnError": true to halt the workflow on failure. To set a specific order status on failure, add ErrorStatus to the properties:

{
  "name": "WebhookWorkflowStep",
  "active": true,
  "Connector": "Webhook",
  "StopOnError": true,
  "Properties": [
    { "Key": "Host", "Value": "https://validation.example.com/api/validate" },
    { "Key": "Authorization", "Value": "Bearer your-token", "KeyGroup": "RequestHeaders" },
    { "Key": "ErrorStatus", "Value": "ValidationFailed" }
  ]
}

Option B: Connector (for shared/reusable config)

If multiple workflow steps need the same endpoint, or you want to manage credentials separately, create a connector in tenant settings and reference it from the workflow step.

Connector (Tenant Settings > Connectors):

{
  "Name": "Webhook",
  "ConnectorId": "my-validation-service",
  "DisplayName": "Order Validation",
  "Host": "https://validation.example.com/api/validate",
  "BearerToken": "your-token-here"
}

Workflow step:

{
  "name": "WebhookWorkflowStep",
  "active": true,
  "Connector": "Webhook",
  "ConnectorId": "my-validation-service",
  "StopOnError": true,
  "Properties": [
    { "Key": "ErrorStatus", "Value": "ValidationFailed" }
  ]
}

The ConnectorId on the workflow step must match the ConnectorId on the connector. If you only have one webhook connector, you can omit ConnectorId on both — it will match by Name alone.

Multiple connectors: You can have several webhook connectors with different ConnectorId values, and reference them from different workflow steps. Connector selection priority: ConnectorId > market match > Name.

Note: If Host is set as a workflow step property, it takes precedence over the connector's Host for the actual HTTP call. You do not need a connector configured to use inline mode.

Request Format

Omnium sends a POST request with the following body:

{
  "Value": {
    "Id": "ORD-12345",
    "Status": "New",
    "CustomerEmail": "customer@example.com",
    "OrderLines": [ ... ],
    "ShippingAddress": { ... },
    "Properties": [ ... ]
  },
  "WorkflowStep": {
    "Name": "WebhookWorkflowStep",
    "Connector": "Webhook",
    "ConnectorId": "my-validation-service",
    "StopOnError": true,
    "Properties": [ ... ]
  },
  "ShipmentId": "SHIP-67890"
}

Value contains the full OmniumOrder object. WorkflowStep contains the step configuration, including any custom properties you added to the step. ShipmentId is included when the step runs in the context of a specific shipment, and identifies which shipment on the order triggered the call — useful because an order can have multiple shipments. The field is omitted when the step is not shipment-scoped.

Headers included automatically:

Plus any custom headers you configure via properties with KeyGroup: "RequestHeaders" on the workflow step (see Setup).

When using a connector, Authorization is set automatically based on the connector's auth config (BearerToken, Username/Password).

Building Your Webhook Endpoint

Your endpoint receives a POST request (see Request Format above) and must return a JSON response that tells Omnium what to do next. The response model is OmniumOrderWorkflowExecutionPatchResult and has two parts:

1. OrderActionExecutionResults — tells Omnium whether the step succeeded or failed
2. OrderPatch (optional) — updates to apply to the order

Success — continue workflow, no changes

Return HTTP 200 with an empty body, {}, or:

{
  "OrderActionExecutionResults": [
    { "ActionStatus": "Success" }
  ]
}

Success — continue workflow, update the order

Include an OrderPatch with the fields you want to change. All fields are optional — only include what you want to update.

{
  "OrderActionExecutionResults": [
    { "ActionStatus": "Success" }
  ],
  "OrderPatch": {
    "Status": "Validated",
    "Tags": ["fraud-checked"],
    "Properties": [
      { "Key": "ValidationScore", "Value": "95" }
    ]
  }
}

Failure — stop the workflow

Set CancelWorkflow to true. If the workflow step has StopOnError enabled, this stops the workflow and sets the order status to ErrorStatus. Use ErrorReason to provide a message visible in the order history.

{
  "OrderActionExecutionResults": [
    {
      "ActionStatus": "Error",
      "CancelWorkflow": true,
      "ErrorReason": "Shipping address could not be validated"
    }
  ]
}

OrderActionExecutionResults fields

OrderPatch fields

The OrderPatch object uses the same model as the PATCH Order API. Key fields you can update:

Status, OrderType, Tags, Properties, StoreId, CustomerEmail, CustomerPhone, CustomerName, BillingAddress, OrderForm (order lines), FollowUpDate, Assets, ExternalIds, OrderNotes, PublicOrderNotes, Errors, OrderOrigin, RelatedOrders, SalesPersonId, SalesPersonName, IsReadOnly, IsNotificationsDisabled

Behavior

On success, an order event is created (operation: ExecuteExportOrder) and any previous WebhookWorkflowStep errors are cleared from the order.

Retry Policy

Failed requests are retried automatically: 3 retries with delays of 1s, 5s, and 15s. Retries are triggered by network errors (timeouts, connection failures) and non-success HTTP responses (except 400 and 404, which are not retried). The X-Delivery-Count header tells your endpoint which attempt this is.

Configuration Reference

Workflow Step Properties

Step-level properties (set inside the Properties array):

Connector Properties

Related Steps

• Export Order — One-way order export (no response handling)