Webhook Return Workflow Step

Overview

The Webhook Return 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 is the return equivalent of the Webhook Workflow Step used in 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. This works identically to the order-side Webhook Workflow Step setup.

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": "WebhookReturnWorkflowStep",
  "active": true,
  "connector": "Webhook",
  "properties": [
    { "key": "Host", "value": "https://erp.example.com/api/returns" },
    { "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": "WebhookReturnWorkflowStep",
  "active": true,
  "connector": "Webhook",
  "stopOnError": true,
  "properties": [
    { "key": "Host", "value": "https://erp.example.com/api/returns" },
    { "key": "Authorization", "value": "Bearer your-token", "keyGroup": "RequestHeaders" },
    { "key": "ErrorStatus", "value": "ReturnFailed" }
  ]
}

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-return-service",
  "DisplayName": "Return Processing Service",
  "Host": "https://erp.example.com/api/returns",
  "BearerToken": "your-token-here"
}

Workflow step:

{
  "name": "WebhookReturnWorkflowStep",
  "active": true,
  "connector": "Webhook",
  "connectorId": "my-return-service",
  "stopOnError": true,
  "properties": [
    { "key": "ErrorStatus", "value": "ReturnFailed" }
  ]
}

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.

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": "Returned",
    "OrderLines": [ ... ],
    "Properties": [ ... ]
  },
  "WorkflowStep": {
    "Name": "WebhookReturnWorkflowStep",
    "Connector": "Webhook",
    "StopOnError": true,
    "Properties": [ ... ]
  },
  "ReturnOrderFormId": "return-form-001"
}

Value contains the full OmniumOrder object. WorkflowStep contains the step configuration, including any custom properties. ReturnOrderFormId identifies which return triggered the workflow, allowing the external system to look up the specific return details.

Headers included automatically:

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

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 — identical to the order-side webhook.

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:

{
  "OrderActionExecutionResults": [
    { "ActionStatus": "Success" }
  ],
  "OrderPatch": {
    "Tags": ["return-synced"],
    "Properties": [
      { "Key": "ERPCreditNoteId", "Value": "CN-789" }
    ]
  }
}

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.

{
  "OrderActionExecutionResults": [
    {
      "ActionStatus": "Error",
      "CancelWorkflow": true,
      "ErrorReason": "Credit note creation failed in ERP"
    }
  ]
}

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, FollowUpDate, Assets, Origin, Errors, Name

Behavior

On success, an order event is created and any previous WebhookReturnWorkflowStep 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

Comparison with Export Order

Related Steps

• Export Order — One-way return export (no response handling)
• Webhook Workflow Step — The equivalent step for order workflows