Webhook Workflow Step

Overview

The Webhook workflow step allows you to execute custom business logic and integrate with external systems via webhooks during order processing. Unlike the basic Export Order step which only sends data, this workflow step can also receive updates back from the external system to modify the order in Omnium.

Important to know:

• The webhook call is awaited - Omnium waits for the external system to respond before continuing
• The execution happens immediately when the workflow step is triggered
• The external system can update the order by returning modified order data
• Failed webhooks can either stop the workflow or just show a warning

Key Difference from Export Order:

• Export Order: One-way communication - sends order data to external systems
• Webhook workflow step: Two-way communication - sends order data AND can receive order updates back

Identifier

Step 1: Configure the Workflow Step

To add webhook workflow steps to your workflow, you need to configure the workflow step properties.

Minimum Required Configuration

At minimum, you must specify the connector:

{
  "Connector": "Webhook"
}

All Available Options

Example Configurations

Example 1: Simple webhook action (warnings only if it fails)

{
  "Connector": "Webhook"
}

Example 2: Critical validation webhook (stop workflow if it fails)

{
  "Connector": "Webhook",
  "ConnectorId": "webhook-fraud-check",
  "StopOnError": true,
  "ErrorStatus": "FraudCheckFailed"
}

Note: This requires a connector with ConnectorId: "webhook-fraud-check" in your tenant settings.

Example 3: Order enrichment webhook (ensure order is saved first)

{
  "Connector": "Webhook",
  "ConnectorId": "webhook-order-enrichment",
  "RunAfterOrderIsSaved": true
}

Step 2: Configure the Webhook Connector

After configuring the workflow step, you need to configure the connector itself in your tenant settings.

Basic Webhook Connector Structure

{
  "Connectors": [
    {
      "Name": "Webhook",
      "DisplayName": "Order Validation Service",
      "Properties": [
        {
          "Key": "WebhookEndpoint",
          "Value": "https://your-domain.com/api/order-actions/validate"
        }
      ]
    }
  ]
}

Authentication Options

Option A: Bearer Token Authentication (Recommended)

{
  "Name": "Webhook",
  "DisplayName": "Workflow Step Service",
  "Host": "https://your-domain.com/api/order-actions/process",
  "BearerToken": "YOUR_API_TOKEN"
}

Option B: Basic Authentication

{
  "Name": "Webhook",
  "Host": "https://your-domain.com/api/order-actions/process",
  "Username": "your-username",
  "Password": "your-password"
}

Option C: Custom Headers

{
  "Name": "Webhook",
  "Properties": [
    {
      "Key": "WebhookEndpoint",
      "Value": "https://your-domain.com/api/order-actions/process"
    },
    {
      "Key": "Authorization",
      "Value": "Bearer YOUR_API_TOKEN",
      "KeyGroup": "RequestHeaders"
    },
    {
      "Key": "X-API-Key",
      "Value": "your-api-key",
      "KeyGroup": "RequestHeaders"
    }
  ]
}

Advanced Configuration Options

Using Multiple Webhook Connectors

When you have multiple webhook endpoints for different purposes (validation, enrichment, fraud detection, etc.), you must:

1. Set a unique ConnectorId on each connector in your tenant settings
2. Reference that specific ConnectorId in your workflow step configuration

Connector Selection Priority:

1. ConnectorId (highest priority) - Selects the exact connector instance
2. Market - Selects market-specific connector if available
3. Name - Falls back to default connector by name

Example: Multiple Webhook Connectors for Different Services

{
  "Connectors": [
    {
      "Name": "Webhook",
      "ConnectorId": "webhook-fraud-check",
      "DisplayName": "Fraud Detection Service",
      "Host": "https://fraud.example.com/api/check",
      "BearerToken": "fraud-token-here"
    },
    {
      "Name": "Webhook",
      "ConnectorId": "webhook-address-validation",
      "DisplayName": "Address Validation Service",
      "Host": "https://address.example.com/api/validate",
      "BearerToken": "address-token-here"
    }
  ]
}

Then in your workflow steps, specify which service to use:

{
  "Connector": "Webhook",
  "ConnectorId": "webhook-fraud-check",
  "StopOnError": true
}

Understanding the Webhook Request and Response

What Gets Sent to Your Webhook?

When the workflow step executes, Omnium sends a POST request with the complete order object:

{
  "Id": "ORD-12345",
  "Status": "Processing",
  "CustomerEmail": "customer@example.com",
  "OrderLines": [
    {
      "ProductId": "PROD-001",
      "Quantity": 2,
      "Price": 199.00,
      "Name": "Example Product"
    }
  ],
  "ShippingAddress": {
    "FirstName": "John",
    "LastName": "Doe",
    "Street": "Example Street 123",
    "City": "Stockholm",
    "PostalCode": "12345",
    "Country": "SE"
  },
  "TotalAmount": 398.00,
  "Currency": "SEK"
}

What Can Your Webhook Return?

Your webhook endpoint can return updated order data that will be applied to the order in Omnium.

Updatable Order Properties:

• Status - Change the order status
• OrderType - Change the order type
• Tags - Add or modify order tags
• Name - Update the order name/title
• Errors - Add or clear error messages
• FollowUpDate - Set a follow-up date
• Assets - Add or modify order assets
• Origin - Update the order origin
• Properties - Add or modify custom properties

Example Response - Update Status and Add Tags:

{
  "Status": "Validated",
  "Tags": ["fraud-checked", "address-verified"],
  "Properties": [
    {
      "Key": "ValidationScore",
      "Value": "95"
    }
  ]
}

Example Response - Add Error:

{
  "Status": "ValidationFailed",
  "Errors": [
    {
      "Code": "InvalidAddress",
      "Message": "Shipping address could not be validated"
    }
  ]
}

Example Response - Success (No Changes): Return HTTP 200 OK with an empty response, or:

{
  "Success": true
}

Behavior

What Happens on Success?

• Order event is created with type "Exported" (operation: ExecuteExportOrder)
• Order properties are updated with data returned from webhook (if any)
• Any previous export errors are cleared
• Workflow continues to the next step

What Happens on Failure?

If StopOnError = false (default):

• A warning is added to the workflow step result
• Workflow continues to the next step

If StopOnError = true:

• An error is added to the workflow step result
• Workflow stops - no further steps execute
• Order status changes to ErrorStatus (if you configured one)

Common Use Cases

Address Validation

{
  "Connector": "Webhook",
  "ConnectorId": "webhook-address-validation",
  "StopOnError": true,
  "ErrorStatus": "AddressValidationFailed"
}

Fraud Detection

{
  "Connector": "Webhook",
  "ConnectorId": "webhook-fraud-check",
  "StopOnError": true,
  "ErrorStatus": "FraudCheckFailed",
  "RunAfterOrderIsSaved": true
}

Order Enrichment (Non-Critical)

{
  "Connector": "Webhook",
  "ConnectorId": "webhook-order-enrichment",
  "RunAfterOrderIsSaved": true,
  "StopOnError": false
}

Multiple Sequential Webhook Actions

You can chain multiple webhook actions in your workflow, each using a different connector instance:

Step 1 - Fraud Check (Critical):

{
  "Connector": "Webhook",
  "ConnectorId": "webhook-fraud-check",
  "StopOnError": true,
  "ErrorStatus": "FraudCheckFailed"
}

Step 2 - Address Validation (Critical):

{
  "Connector": "Webhook",
  "ConnectorId": "webhook-address-validation",
  "StopOnError": true,
  "ErrorStatus": "ValidationFailed"
}

Step 3 - Customer Enrichment (Non-critical):

{
  "Connector": "Webhook",
  "ConnectorId": "webhook-customer-enrichment",
  "StopOnError": false,
  "RunAfterOrderIsSaved": true
}

Complete Configuration Example

Step 1: Configure the Connector in Tenant Settings

{
  "Connectors": [
    {
      "Name": "Webhook",
      "ConnectorId": "webhook-order-validation",
      "DisplayName": "Order Validation Service",
      "Host": "https://validation.yourcompany.com/api/validate-order",
      "BearerToken": "your-secret-validation-token",
      "Timeout": "00:00:30",
      "Properties": [
        {
          "Key": "X-Service-Version",
          "Value": "v2",
          "KeyGroup": "RequestHeaders"
        }
      ]
    }
  ]
}

Step 2: Configure the Workflow Step

Add this workflow step to your Order Type (e.g., in the "New" status):

{
  "name": "WebhookWorkflowStep",
  "active": true,
  "runAfterOrderIsSaved": false,
  "stopOnError": true,
  "Connector": "Webhook",
  "ConnectorId": "webhook-order-validation",
  "ErrorStatus": "ValidationFailed",
  "TranslateKey": "WorkflowStep_ValidateOrder"
}

Note: The ConnectorId must match the ConnectorId field in your connector configuration.

How it works:

1. When an order is created and reaches "New" status, the WebhookWorkflowStep executes
2. Omnium sends the complete order to your validation endpoint with bearer token authentication
3. Your service validates the order and returns a response
4. If validation succeeds, order is updated with your response data and workflow continues
5. If validation fails, workflow stops and order status changes to "ValidationFailed"

Error Handling

Troubleshooting

Webhook Not Executing

1. Is the connector name spelled correctly? (it's case-sensitive!)
2. Is the connector configured in Tenant Settings?
3. Does the order's workflow actually reach this step?
4. Check the order events log for "Exported" event with operation ExecuteExportOrder

Webhook Timeout

• Increase the Timeout value in connector configuration (default is usually 30 seconds)
• Optimize your webhook endpoint to respond faster
• Consider making your webhook asynchronous - return 200 OK immediately and update order later via API

Order Not Updated from Webhook Response

1. Is your webhook returning valid JSON?
2. Are you returning the correct property names (case-sensitive)?
3. Ensure you're returning HTTP 200 OK status

Valid properties that can be updated: Status, OrderType, Tags, Name, Errors, FollowUpDate, Assets, Origin, Properties

Stale Data Issues

Set RunAfterOrderIsSaved: true in your workflow step to ensure the order is fully saved before the webhook executes.

Related Steps

• Export Order - One-way order export to external systems
• Notification - Send notifications