Webhook(en)

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

Indroduction

This is Boxful WEBHOOK API document, only for Boxful fulfillment merchant.

Region

Hook Post Unified Format

The main data is placed in the payload parameter. Please refer to the response format for each event type.

If you want to verify the reliability of the data source, decode the validator_code to obtain the complete payload.

{
  "timestamp": 1608202713,
  "region": "tw",
  "event_type": "shipment_logistics",
  "event": "update",
  "payload": {},
  "validator_code": "..."
}

Reliability Verification

Reliability verification use AES-256-CBC encryption Fill the number 0 to 16 digits to the left The final result is the timestamp of the data uploaded by Hook

function decryptValidatorCode($data = "", $token = "", $handle = "")
{
    $output = '';
    $handle = str_pad($handle, 16, '0', STR_PAD_LEFT);
    $string = openssl_decrypt(hex2bin($data), 'AES-256-CBC', $token, OPENSSL_RAW_DATA | OPENSSL_ZERO_PADDING,
        $handle);
    $string_ascii = ord(substr($string, -1));
    $stringing_chr = chr($string_ascii);
    if (preg_match("/$stringing_chr{" . $string_ascii . "}/", $string)) {
        $string = substr($string, 0, strlen($string) - $string_ascii);
        parse_str($string, $output);
    }
    return $output;
}

Event URL Configuration

Please provide the event category, event item, and the target URL to Boxful. Example: shipment_logistics.create http://api.boxful.com/webhook_url

Event List

HEAD /Webhook-Description

Event Overview

event_type	event	Triggered when	Response Format
`pickup`	`main_update`	An inbound order (PL) is modified	`pickup_main_update`
`pickup`	`item_update`	An inbound order item is modified	`pickup_item_update`
`logistics`	`create`	A shipment logistics record is created	`shipment_and_logistics`
`logistics`	`update`	Any of carrier, logistics status, dispatch time or tracking number is modified	`shipment_and_logistics`
`reverse`	`create`	A reverse logistics order is created	`reverse_create`
`reverse`	`update`	A reverse logistics order is modified	`reverse_update`
`inventory`	`low_warning`	Notified once a day when a product reaches its stock level warning threshold	`inventory_low_warning`

Notes for Receivers

Respond with HTTP 200. Any other status code is treated as a failure. A message is retried at most 3 times; after that it is dropped and will not be re-sent later.
Recipient data is masked in the Taiwan region. In Taiwan, name, phone and address are returned partially masked (for example 測*1, 09*****234). Hong Kong and Korea return the original values.

Reference Tables

The tables below are shared by all events.

Shipment Status

Applies to status (shipment order status) and logistics[].logistics_status (per-parcel status) of shipment_and_logistics.

status	Description
`order_created`	Order created
`assigned_picking`	Picking assigned
`picked`	Picking completed
`picking_checked`	Picking inspection completed
`shipment`	Shipped
`closed`	Delivered and closed

Inbound Order Status

Applies to status_code of pickup_main_update.

status_code	Description
`0`	Awaiting inbound. Booking confirmed, goods have not arrived yet
`1`	Goods have arrived at the warehouse, inbound processing not finished
`2`	Inbound completed

Inbound Item Status

Applies to status of pickup_item_update. The normal flow is padding → padding_qc → machining → assign_position → stored.

status	Description
`padding`	Awaiting inbound processing
`padding_qc`	Quality inspection in progress
`machining`	Processing in progress
`assign_position`	Storage location being assigned
`stored`	Inbound completed, stock is available
`lack`	Item shortage

Reverse Status

Applies to status of reverse_create / reverse_update.

status.id	Description
`1`	Reverse logistics requested
`2`	Awaiting carrier assignment
`3`	Picked up, in transit
`4`	Arrived at the warehouse
`5`	Reverse logistics closed
`6`	Exception, awaiting resolution
`7`	Reverse logistics cancelled

status is an object containing id, label (code) and description (text description).

Reverse Item Status

Applies to reverse_goods[].status.

status	Description
`1`	Awaiting return to the warehouse
`2`	Returned to the warehouse
`3`	Cancelled

Inbound Delivery Method

Applies to logistics_code of pickup_main_update.

logistics_code	Description
`own-self`	Self-delivery or supplier direct delivery
`boxful`	BOXFUL vehicle dispatch
`processing_in_warehouse`	In-warehouse processing

Retrieve Type

Applies to retrieve_type, retrieving_type, expected_entering_type and actual_entering_type.

Value	Description
`piece_out`	By piece
`item_out`	By carton
`pallet_out`	By pallet
`bundle_out`	Bundle product

Inbound

EventType
pickup

Event	Description	Response Format Ref.
main_update	Inbound order (PL) update	pickup_main_update
item_update	Inbound item status update	pickup_item_update

pickup_main_update Fields

pickup_main_update Response Format

{
  "timestamp": 1608726033,
  "region": "tw",
  "event_type": "pickup",
  "event": "main_update",
  "payload": {
    "packing_order_id": "TWI1601283742",
    "name": "OwenShih",
    "phone": "0800050777",
    "address": "台北市松山區光復北路11巷44號11樓",
    "email": "owen@boxful.com.tw",
    "logistics_date": "2020-12-20",
    "logistics_time_slot": "1100-1200",
    "logistics_code": "own-self",
    "logistics_label": "自行出貨",
    "is_container": 0,
    "is_custom": 0,
    "status_code": 1,
    "status_label": "Packing已抵達倉庫"
  },
  "validator_code": "9455f62917ba803bdafa4ddd3112d90a0360729"
}

Field	Type	Description
`packing_order_id`	string	Inbound order number, formatted as `region code + I + 10 characters`, for example `TWI1601283742`
`name`	string	Delivery contact person
`phone`	string	Delivery contact phone
`address`	string	Delivery address
`email`	string	Contact email
`logistics_date`	string	Booked inbound date
`logistics_time_slot`	string	Booked inbound time slot
`logistics_code`	string	Delivery method code, see Inbound Delivery Method
`logistics_label`	string	Delivery method name
`is_container`	int	Whether devanning is required, `1` yes / `0` no
`is_custom`	int	Whether the goods enter the warehouse through customs, `1` yes / `0` no
`status_code`	int	Inbound order status, see Inbound Order Status
`status_label`	string	Status name

pickup_item_update Fields

pickup_item_update Response Format

{
  "timestamp": 1612346367,
  "region": "tw",
  "event_type": "pickup",
  "event": "item_update",
  "payload": {
    "id": 48897,
    "label": "Demo product",
    "description": null,
    "sku": "A001(132777)",
    "barcode": "4711769132777",
    "expiry_date": null,
    "status": "machining",
    "status_description": "加工中",
    "logistics_date": "2021-02-03",
    "packing_order_id": "TWI1616676633",
    "out_bound_total_count": 200,
    "receive": [
      {
        "expected_entering_type": "item_out",
        "expected_entering_type_label": "箱出",
        "expected_entering_count": 10,
        "actual_entering_type": "item_out",
        "actual_entering_type_label": "箱出",
        "actual_entering_count": 10,
        "receive_detail": [
          {
            "count": 10,
            "unit_count": 20,
            "total_count": 200,
            "is_defective": 0
          }
        ]
      }
    ]
  },
  "validator_code": "b3fe1376718eb05e1a0b21e2ec412712"
}

Field	Type	Description
`id`	int	Inbound item sequence number
`label`	string	Product name
`description`	string	Product description
`sku`	string	Product SKU
`barcode`	string	Product barcode
`expiry_date`	string	Expiry date
`status`	string	Item status, see Inbound Item Status
`status_description`	string	Status description
`logistics_date`	string	Booked inbound date of the parent inbound order
`packing_order_id`	string	Inbound order number this item belongs to
`out_bound_total_count`	int	Total quantity actually received for this item
`receive`	array	Receiving details, grouped by entering type
`receive[].expected_entering_type`	string	Expected entering type, see Retrieve Type
`receive[].expected_entering_type_label`	string	Expected entering type name
`receive[].expected_entering_count`	int	Expected quantity
`receive[].actual_entering_type`	string	Actual entering type
`receive[].actual_entering_type_label`	string	Actual entering type name
`receive[].actual_entering_count`	int	Actual quantity
`receive[].receive_detail`	array	Receiving details
`receive[].receive_detail[].count`	int	Number of cartons or pieces
`receive[].receive_detail[].unit_count`	int	Quantity contained in each unit
`receive[].receive_detail[].total_count`	int	Subtotal, `count × unit_count`
`receive[].receive_detail[].is_defective`	int	Whether the goods are defective, `1` yes / `0` no

Inventory

EventType
inventory

Event	Description	Response Format Ref.
low_warning	Notified once a day when a product reaches its stock level warning threshold	inventory_low_warning

inventory_low_warning Fields

inventory_low_warning Response Format

{
  "timestamp": 1612410721,
  "region": "tw",
  "event_type": "inventory",
  "event": "low_warning",
  "payload": {
    "label": "demo001",
    "barcode": "15893383605698102",
    "sku": "demo001",
    "safety_stock": 99999999,
    "retrieving_type": "piece_out"
  },
  "validator_code": "546a8aa577c091eb53017b46f95d8a5be5cb310c8"
}

Field	Type	Description
`label`	string	Product name
`barcode`	string	Product barcode
`sku`	string	Product SKU
`safety_stock`	int	Safety stock level
`retrieving_type`	string	Outbound type, see Retrieve Type

Logistics

EventType
logistics

Event	Description	Response Format Ref.
create	Triggered when a shipment logistics record is created	shipment_and_logistics
update	Triggered when carrier, logistics status, dispatch time or tracking number is modified	shipment_and_logistics

shipment_and_logistics Fields

shipment_and_logistics Response Format

{
  "timestamp": 1344544545,
  "region": "tw",
  "event_type": "logistics",
  "event": "update",
  "payload": {
    "logistics_date": "2019-07-29",
    "address": "台北市*****11樓",
    "name": "王*明",
    "phone": "09*****678",
    "instruction": "付單",
    "2b_schedule_id": "1496",
    "collect_amount": 0,
    "vendor_order_id": "7142",
    "wms_order_id": "15641381475151991034",
    "status": "closed",
    "logistics": [
      {
        "logistics_vendor": "Boxful跨境配",
        "logistics": "boxful_corss",
        "logistics_status": "shipment",
        "service_at": "2019-07-28 12:00:00",
        "logistics_status_label": "已出貨",
        "logistics_code": "xdJ5jc",
        "tracking_url": "https://t.boxful.tw/1TDPGE"
      }
    ]
  },
  "validator_code": "92a2124ba634da84fb343514cc78cebfc8"
}

Field	Type	Description
`logistics_date`	string	Expected shipment date
`name`	string	Recipient name
`phone`	string	Recipient phone
`address`	string	Recipient address
`instruction`	string	Shipment remark
`2b_schedule_id`	string	OMS ORDER ID
`collect_amount`	int	Cash on delivery amount. `0` means not a COD order
`vendor_order_id`	string	Custom order number
`wms_order_id`	string	WMS shipment order number
`status`	string	Shipment order status, see Shipment Status
`logistics`	array	Parcel list, one entry per parcel
`logistics[].logistics`	string	Carrier code
`logistics[].logistics_vendor`	string	Carrier name
`logistics[].logistics_status`	string	Parcel status, see Shipment Status
`logistics[].logistics_status_label`	string	Parcel status description
`logistics[].logistics_code`	string	Tracking number
`logistics[].service_at`	string	Carrier dispatch or pickup time
`logistics[].tracking_url`	string	Tracking page URL

Reverse

EventType
reverse

Event	Description	Response Format Ref.
create	Triggered when a reverse logistics order is created	reverse_create
update	Triggered when a reverse logistics order is modified	reverse_update

reverse_create / reverse_update Fields

reverse_create Response Format

{
  "timestamp": 1784191910,
  "region": "tw",
  "event_type": "reverse",
  "event": "create",
  "payload": {
    "reverse_order_id": "TWR1795402890",
    "name": "測*1",
    "phone": "09*****234",
    "address": "嘉義市 嘉義*****站",
    "logistics_date": "2026-07-16",
    "closed_at": null,
    "instruction": "商品瑕疵",
    "back_and_forth": 0,
    "created_at": "2026-07-16 10:37:41",
    "status": {
      "id": 1,
      "label": "application",
      "description": "申請逆物流"
    },
    "shipment": {
      "wms_order_id": "DEMOO_0014976209",
      "vendor_order_id": "0014976209",
      "2b_schedule_id": "7843991",
      "order_source_id": "0014976209"
    },
    "logistics": {
      "logistics": "hct",
      "description": "新竹物流(常溫)",
      "tracking_number": "FAKE_LOGISTICS_CODE",
      "packing_number": 1
    },
    "reverse_goods": [
      {
        "id": 232580,
        "expected_count": 1,
        "real_count": 0,
        "normal_count": 0,
        "abnormal_count": 0,
        "status": 1,
        "barcode": "DEMO_BARCODE_253342",
        "sku": "DEMO_SKU_253342",
        "label": "DEMO_253342號_商品",
        "expiry_date": "",
        "retrieve_type": "piece_out"
      }
    ]
  },
  "validator_code": "595d85906823b19628519f8e2cd738467efb17cbcbd7bcf3833d4cd9cc52b6af"
}

reverse_update Response Format

{
  "timestamp": 1784192530,
  "region": "tw",
  "event_type": "reverse",
  "event": "update",
  "payload": {
    "reverse_order_id": "TWR1795402890",
    "name": "測*1",
    "phone": "09*****234",
    "address": "嘉義市 嘉義*****站",
    "logistics_date": "2026-07-16",
    "closed_at": "2026-07-18 15:02:11",
    "instruction": "商品瑕疵",
    "back_and_forth": 0,
    "created_at": "2026-07-16 10:37:41",
    "status": {
      "id": 5,
      "label": "closed",
      "description": "逆物流結案"
    },
    "shipment": {
      "wms_order_id": "DEMOO_0014976209",
      "vendor_order_id": "0014976209",
      "2b_schedule_id": "7843991",
      "order_source_id": "0014976209"
    },
    "logistics": {
      "logistics": "hct",
      "description": "新竹物流(常溫)",
      "tracking_number": "FAKE_LOGISTICS_CODE",
      "packing_number": 1
    },
    "reverse_goods": [
      {
        "id": 232580,
        "expected_count": 1,
        "real_count": 1,
        "normal_count": 1,
        "abnormal_count": 0,
        "status": 2,
        "barcode": "DEMO_BARCODE_253342",
        "sku": "DEMO_SKU_253342",
        "label": "DEMO_253342號_商品",
        "expiry_date": "",
        "retrieve_type": "piece_out"
      }
    ]
  },
  "validator_code": "595d85906823b19628519f8e2cd738467efb17cbcbd7bcf3833d4cd9cc52b6af"
}

Field	Type	Description
`reverse_order_id`	string	Reverse logistics order number, formatted as `region code + R + 10 characters`, for example `TWR1795402890`
`name`	string	Pickup contact person
`phone`	string	Pickup contact phone
`address`	string	Pickup address
`logistics_date`	string	Expected collection date
`closed_at`	string	Closing time
`instruction`	string	Reverse logistics reason or remark
`back_and_forth`	int	Whether it is a round trip parcel, `1` yes / `0` no
`created_at`	string	Creation time
`status`	object	Reverse logistics status, see Reverse Status
`shipment.wms_order_id`	string	WMS shipment order number of the original shipment
`shipment.vendor_order_id`	string	Custom order number of the original shipment
`shipment.2b_schedule_id`	string	OMS ORDER ID of the original shipment
`shipment.order_source_id`	string	Source platform order number of the original shipment
`logistics.logistics`	string	Reverse carrier code
`logistics.description`	string	Reverse carrier name
`logistics.tracking_number`	string	Reverse tracking number
`logistics.packing_number`	int	Parcel count
`reverse_goods`	array	Reverse logistics item list
`reverse_goods[].id`	int	Reverse logistics item sequence number
`reverse_goods[].expected_count`	int	Expected return quantity
`reverse_goods[].real_count`	int	Quantity actually returned to the warehouse
`reverse_goods[].normal_count`	int	Quantity in good condition
`reverse_goods[].abnormal_count`	int	Quantity in abnormal condition
`reverse_goods[].status`	int	Item status, see Reverse Item Status
`reverse_goods[].barcode`	string	Product barcode
`reverse_goods[].sku`	string	Product SKU
`reverse_goods[].label`	string	Product name
`reverse_goods[].expiry_date`	string	Expiry date
`reverse_goods[].retrieve_type`	string	Original outbound type, see Retrieve Type

Example responses

200 Response

Responses

Status	Meaning	Description	Schema
200	OK	successful operation	Inline

Response Schema

Status Code 200

empty object

Name	Type	Required	Restrictions	Description