> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/oms/webhooks/webhook-examples/order-split-package-event-webhook.md).

# Order Split Package Event Webhook

## <mark style="color:red;">What is OrderSplitPackageEvent?</mark>

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

### <mark style="color:red;">Why This Webhook Matters</mark>

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.

### <mark style="color:red;">How Channel Filtering Works</mark>

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.

#### <mark style="color:red;">Channel ID Examples</mark>

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

**Path:** Package → Order → channel\_id

### <mark style="color:red;">Endpoint: Configure the Webhook</mark>

```
POST /oms_hooks/
```

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

#### <mark style="color:red;">Important Notes</mark>

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.

#### <mark style="color:red;">Channel Configuration</mark>

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.

#### <mark style="color:red;">Authentication</mark>

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

### <mark style="color:red;">Request Body</mark>

`Content-Type: application/json` → see `WebhookConfiguration`.

#### <mark style="color:red;">Example: Website Channel</mark>

Configure a webhook for the main e-commerce website.

```json
{
  "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
    }
  }
}
```

#### <mark style="color:red;">Example: Mobile App Channel</mark>

Configure a webhook for mobile app orders.

```json
{
  "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
    }
  }
}
```

#### <mark style="color:red;">Example: Amazon Marketplace Channel</mark>

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
    }
  }
}
```

### <mark style="color:red;">Responses</mark>

#### <mark style="color:red;">`201`</mark> <mark style="color:red;">— Webhook configured successfully</mark>

```json
{
  "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"
}
```

#### <mark style="color:red;">`400`</mark> <mark style="color:red;">— Invalid configuration</mark>

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

### <mark style="color:red;">Schema:</mark> <mark style="color:red;">`WebhookConfiguration`</mark>

**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`.                                        |

{% hint style="warning" %}
Do **not** use old formats like `order.split_package_1`. The only valid value is `order.split_package`.
{% endhint %}

#### <mark style="color:red;">`config`</mark> <mark style="color:red;">object</mark>

| 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:**

```json
{
  "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`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.akinon.com/technical-guides/oms/webhooks/webhook-examples/order-split-package-event-webhook.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.