Order Split Package Event Webhook

What is OrderSplitPackageEvent?

The OrderSplitPackageEvent webhook is triggered when an order gets split into multiple packages during the fulfillment planning process. This happens when the fulfillment engine determines that items from a single order must be packaged separately based on:

• Different stock locations: Items are available in different warehouses
• Planning optimization: The fulfillment engine creates optimal delivery strategies
• Inventory distribution: Items have different availability across multiple locations

Why This Webhook Matters

The OrderSplitPackageEvent webhook is specifically designed for marketplace integrations. When an order splits into multiple packages during fulfillment planning, marketplace channels need to be notified.

How Channel Filtering Works

The system uses a smart filtering mechanism:

1. Order Processing: When an order from channel X gets split into packages
2. Webhook Lookup: System searches for webhooks with:

   • event_type = "order.split_package"
   • config.channel_id = X
3. Event Delivery: If matching webhook found, sends notification to that endpoint.
4. Fallback: If no channel-specific webhook found, may send general notification.

Channel ID Examples

The channel_id corresponds to the sales channel ID from your OMS system. To find the correct channel IDs:

Path: Package → Order → channel_id

Endpoint: Configure the Webhook

POST /oms_hooks/

Configures a webhook to receive notifications when orders split into multiple packages.

Important Notes

1. Event Type — must always be order.split_package.
2. Channel ID — must match your sales channel identifier.
3. Target URL — must be HTTPS and publicly accessible.

Channel Configuration

Each sales channel needs its own webhook configuration. You can:

• Use the same target URL for multiple channels (differentiate by channel_id in payload).
• Use different target URLs for different processing logic.
• Configure different retry policies per channel.

Authentication

Scheme	Type	Location	Name
ApiKeyAuth	API key	header	X-API-Key

Request Body

Content-Type: application/json → see WebhookConfiguration.

Example: Website Channel

Configure a webhook for the main e-commerce website.

{
  "event_type": "order.split_package",
  "target_url": "https://mystore.com/webhooks/order-split",
  "config": {
    "channel_id": 1
  },
  "additional_headers": {
    "Authorization": "Token your-api-token"
  },
  "is_active": true,
  "retry_countdown_config": {
    "choice": "exponential",
    "kwargs": {
      "base": 2,
      "factor": 1
    }
  }
}

Example: Mobile App Channel

Configure a webhook for mobile app orders.

{
  "event_type": "order.split_package",
  "target_url": "https://api.mystore.com/mobile/webhooks/order-split",
  "config": {
    "channel_id": 2
  },
  "additional_headers": {
    "Authorization": "Token mobile-api-token"
  },
  "is_active": true,
  "retry_countdown_config": {
    "choice": "fixed",
    "kwargs": {
      "seconds": 120
    }
  }
}

Example: Amazon Marketplace Channel

Configure a webhook for Amazon marketplace orders.

{
  "event_type": "order.split_package",
  "target_url": "https://logistics.mystore.com/amazon/order-notifications",
  "config": {
    "channel_id": 3
  },
  "additional_headers": {
    "X-API-Key": "amazon-integration-key"
  },
  "is_active": true,
  "secret_key": "webhook-secret-key",
  "retry_countdown_config": {
    "choice": "linear",
    "kwargs": {
      "delay": 60
    }
  }
}

Responses

201 — Webhook configured successfully

{
  "id": 199,
  "target_url": "https://mystore.com/webhooks/order-split",
  "event_type": "order.split_package",
  "is_active": true,
  "config": {
    "channel_id": 199
  },
  "retry_countdown_config": {
    "choice": "fixed",
    "kwargs": {
      "seconds": 120
    }
  },
  "additional_headers": {
    "Authorization": "Token 3e934f533b235a6a7c7a15faa08d1db7204205df"
  },
  "secret_key": null,
  "callback": null,
  "created_date": "2025-10-28T09:42:38.033715Z",
  "modified_date": "2025-10-28T09:42:38.033733Z"
}

400 — Invalid configuration

{
  "error": "channel_id is required in config",
  "details": {
    "config": ["channel_id field is required"]
  }
}

Schema: WebhookConfiguration

Required fields: event_type, target_url, config, additional_headers, retry_countdown_config

Field	Type	Required	Description
target_url	string (uri)	✅	Your webhook endpoint URL. Must use HTTPS and return HTTP 200 on success.
event_type	string (enum)	✅	Must always be order.split_package.
config	object	✅	Webhook configuration settings (see below).
additional_headers	object<string,string>	✅	HTTP headers sent with each webhook request (e.g. auth tokens, custom source headers).
retry_countdown_config	object	✅	Retry strategy for failed deliveries (see below).
secret_key	string	⬜	Optional secret used to verify the authenticity of webhook requests.
callback	string	⬜	Optional callback configuration or URL for webhook responses.
is_active	boolean	⬜	Whether the webhook is active. Default: true.

Do not use old formats like order.split_package_1. The only valid value is order.split_package.

config object

Field	Type	Required	Constraints	Description
channel_id	integer	✅	minimum: 1	The sales channel ID you want to monitor.

How channel_id works:

• An order comes from, say, channel 3 (Amazon).
• The system searches for a webhook with config.channel_id = 3.
• If found, the notification is sent to that webhook.
• If not found, no channel-specific notification is sent.

Where to find it: OMS → Packages → Order → channel_id

retry_countdown_config object

Field	Type	Description
choice	string (enum)	Retry strategy: exponential, linear, or fixed.
kwargs	object	Strategy-specific parameters (see below).

Strategy parameters (kwargs):

Strategy	Parameter	Type	Description	Example
fixed	seconds	integer	Fixed delay in seconds.	120
exponential	base	integer	Base value for exponential backoff.	2
exponential	factor	integer	Multiplication factor for retry delay.	1
linear	delay	integer	Base delay for linear increase.	60

Default example:

{
  "choice": "fixed",
  "kwargs": { "seconds": 120 }
}

---

Servers

URL	Description
https://{domain}/api/v1/oms	Your OMS API server (default domain sandbox.akinon.com)
https://your-webhook-server.com	Your webhook endpoint server

Supported Code Sample Languages

curl · python · javascript · php