# Webhook Mechanism

# Introduction

Product details including addition, deletion & modification of variants.

# Setup Procedure

  • 1)Set up message monitoring and reference.webhook
  • 2)Set up client monitoring interface, example as below(Java).
  • 3)Test monitoring.

# Webhook Configuration Requirements

# 1. Protocol Requirements

  • Supported Protocols: HTTPS
  • Encryption: TLS 1.2 or TLS 1.3 recommended for secure transmission
  • Request Method: POST
  • Content Type: Content-Type: application/json

# 2. Response Specifications

  • Success Status Code: 200 OK
  • Timeout: Response must be returned within 3 seconds
    (Avoid long-running or complex business logic to ensure prompt response)

# List of topics

# Product Message: PRODUCT

# Occurs when a product is created or updated.

  • Sample Payload
{
    "messageId": "ca72a4834cd14b9588e88ce206f614a0",
    "type": "PRODUCT",
    "params": {
        "categoryId": null,
        "categoryName": null,
        "pid": "1424608189734850560",
        "productDescription": "xxxxxx",
        "productImage": null,
        "productName": null,
        "productNameEn": null,
        "productProperty1": null,
        "productProperty2": null,
        "productProperty3": null,
        "productSellPrice": null,
        "productSku": null,
        "productStatus": null,
        "fields" : [
            "productDescription"
        ],
    }
}
Parameter Definition Type Required Length Note
messageId Message Id string Y 200 Message Id
type Message type string Y 200 PRODUCT,VARIANT
params object Y 5
- categoryId category Id string Y 200
- categoryName category Name string Y 200
- pid product id string Y 200
- productDescription product description string Y 2000
- productImage product image string Y 200
- productName product name string Y 200
- productNameEn product name(english) string Y 200
- productProperty1 product property string Y 200
- productProperty2 product property string Y 200
- productProperty3 product property string Y 200
- productSellPrice product sell price double Y 20
- productSku product sku string Y 200
- productStatus product status int Y 5
- fields fields list list Y 5

Product Status

ProductStatus Description
0 Deleted
1 To be submitted
2 Pending
3 On sale
4 Audit failure
5 Off sale
6 To be reviewed

# Inbound message for Variant

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "VARIANT",
    "params": {
        "vid": "1424608152007086080",
        "variantName": null,
        "variantWeight": null,
        "variantLength": null,
        "variantWidth": null,
        "variantHeight": null,
        "variantImage": null,
        "variantSku": null,
        "variantKey": null,
        "variantSellPrice": null,
        "variantStatus": null,
        "variantValue1": null,
        "variantValue2": null,
        "variantValue3": null,
        "fields" : [
            "variantLength"
        ],
    }
}
Parameter Definition Type Required Length Note
messageId Message id string Y 200 Message Id
type Message type string Y 200 PRODUCT,VARIANT
params object Y 5
- vid variant Id string Y 200
- variantName variant name string Y 200
- variantWeight variant weight int Y 200
- variantLength variant length int Y 2000
- variantWidth variant width int Y 200
- variantHeight variant height int Y 200
- variantImage variant name(english) string Y 200
- variantSku variant sku string Y 200
- variantKey variant key string Y 200
- variantSellPrice variant sell price double Y 200
- variantStatus variant status int Y 5
- variantValue1 variant value1 string Y 200
- variantValue2 variant value2 string Y 200
- variantValue3 variant value3 string Y 200
- fields fields list list Y 5

Variant Status

ProductStatus Description
0 Off sale
1 On sale
null On sale

# Stock Message

{
    "messageId": "ca72a4834cd14b9588e88ce206f614a0",
    "type": "STOCK",
    "params": {
        "1424608152007086080": [
            {
                "vid": "1424608152007086080",
                "areaId": "2",
                "areaEn": "US Warehouse",
                "countryCode": "US",
                "storageNum": 12
            }
        ],
        "AE7DB9BC-4290-4C85-B8A6-F8957F3DB053": [
            {
                "vid": "AE7DB9BC-4290-4C85-B8A6-F8957F3DB053",
                "areaId": "2",
                "areaEn": "US Warehouse",
                "countryCode": "US",
                "storageNum": 1
            }
        ]
    }
}

# Order message

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "ORDER",
    "params": {
        "orderNumber": "api_52f268d40b8d460e82c0683955e63cc9",
        "cjOrderId": 210823100016290555,
        "orderStatus": "CREATED",
        "logisticName": "CJPacket Ordinary",
        "trackNumber": null,
        "createDate": "2021-08-23 11:31:45",
        "updateDate": "2021-08-23 11:31:45",
        "payDate": null,
        "deliveryDate": null,
        "completeDate": null
    }
}
Parameter Definition Type Required Length Note
cjOrderId CJ order id string Y 200
orderNum Customer order number string Y 200 Will be deprecated, please use orderNumber instead
orderNumber Customer order number string Y 200
orderStatus CJ order status string Y 200
logisticName logistic name string Y 200
trackNumber track number string Y 200
updateDate update date string Y 200
createDate create date string Y 200
payDate pay date string Y 200
deliveryDate delivery date string Y 200
completeDate complete date string Y 200

# Order splitting message

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "ORDERSPLIT",
    "params": {
        "originalOrderId": "original order id",
        "splitOrderList": [
            {
                "createAt":1673490845706,
                "orderCode":"SD1613355441583259648-2",
                "orderStatus":300,
                "productList":[
                {
                    "sku":"CJNSSYLY01043-Claret-S",
                    "vid":"2547992D-CEE1-4BFD-99AC-9E30354F771F",
                    "quantity":1,
                    "productCode":"1613355657229205504"
                },
                {
                    "sku":"CJJSAQXF00016-Orange",
                    "vid":"A9C95BCB-D824-4AA1-A389-E86F3CCB10EF",
                    "quantity":1,
                    "productCode":"1613355657229205506"
                },
                {
                    "sku":"CJNSSYCS03214-Photo Color-XXL",
                    "vid":"E5FED43E-F9DE-483F-ADCE-8C95D3380315",
                    "quantity":1,
                    "productCode":"1613355657229205507"
                }
                ]
            },
            {
                "createAt":1673490845706,
                "orderCode":"SD1613355441583259648-1",
                "orderStatus":300,
                "productList":[
                    {
                        "sku":"CJNSSYLY01043-White-M",
                        "vid":"0550DFC6-7FF7-4662-AE7D-B4DF0E4EB24A",
                        "quantity":1,
                        "productCode":"1613355657229205505"
                    }
                ]
            }
        ],
        "orderSplitTime": "拆单时间"
    }
}
Parameter Definition Type Length Note
originalOrderId original CJ order id string 200
splitOrderList list
orderCode CJ order id string 200
createAt create date string 200
orderStatus order status int 11
productList product information list 200
productCode product code string 200
vid variant id string 200
quantity quantity int 10
sku sku string 200
orderSplitTime order split date string 200

# Source product creation result

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "SOURCINGCREATE",
    "params": {
        "cjProductId":"0550DFC6-7FF7-4662-AE7D-B4DF0E4EB24A",
        "cjVariantId":"0550DFC6-7FF7-4662-AE7D-B4DF0E4EB24A",
        "cjVariantSku":"CJ123582565212",
        "cjSourcingId":"125522",
        "status": "completed",
        "failReason":"",
        "createDate": "2023-02-07 00:00:00"
    }
}
返回字段 字段意思 字段类型 长度 备注
cjProductId CJ product id string 100
cjVariantId CJ variant id string 100
cjVariantSku CJ variant sku string 50
cjSourcingId CJ sourcing Id string 50
status status string 20
failReason fail reason string 20
createDate create date String 50

# Logistics message

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "LOGISTIC",
    "params": {
        "orderId": 210823100016290555,
        "logisticName": "CJPacket Ordinary",
        "trackingNumber": "number12345678",
        "trackingStatus": "12",
        "logisticsTrackEvents": "[{\"status\":12,\"activity\":\" Delivered, PO Box\",\"location\":\" NENANA,AK 99760\",\"eventTime\":\"2024-01-18 07:59:22\",\"statusDesc\":\"Delivered\",\"thirdActivity\":\"Delivered, PO Box\",\"thirdLocation\":\"NENANA,AK 99760\",\"thirdEventTime\":\"2024-01-18 07:59:22\"}]"
    }
}

todo: Inconsistent field naming between English and Chinese docs: 'orderNum' is deprecated in both places; ensure 'orderNumber' is primary and 'orderNum' marked deprecated (already adjusted in table). Reason: keep API payload consistent.

Parameter Definition Type Required Length Note
orderId CJ order id string Y 200 210823100016290555
logisticName logistic name string Y 200 CJPacket Ordinary
trackingNumber track number string Y 200 number12345678
trackingStatus tracking status string Y 20 0- No tracking information available at the moment 1- Warehouse outbound 2- Freight forwarder inbound 3- Freight forwarder return 4- Freight forwarder outbound 5- First leg transportation 6- Arrival at destination country 7- Starting customs clearance 8- Customs clearance completed 9- Terminal retrieval 10- Delivery 11- Arrival waiting for retrieval 12- Sign for 13- Failure/abnormality 14- Return
logisticsTrackEvents logistics track events string Y 200 [{"status":12,"activity":" Delivered, PO Box","location":" NENANA,AK 99760","eventTime":"2024-01-18 07:59:22","statusDesc":"Delivered","thirdActivity":"Delivered, PO Box","thirdLocation":"NENANA,AK 99760","thirdEventTime":"2024-01-18 07:59:22"}]

# Listening example

# Example

package com.cj.cn.controller;

import com.alibaba.fastjson.JSON;
import com.cj.cn.constant.callback.domain.CallbackParams;
import com.cj.cn.util.result.Result;
import lombok.extern.slf4j.Slf4j;
import org.springframework.validation.annotation.Validated;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

/**
 * CJ Webhook Listening Example
 *
 * @author : kay
 */
@RestController
@RequestMapping("/webhookListener")
@Slf4j
public class TestController {

    @PostMapping("/productMessage")
    public Result productMessage(@RequestBody @Validated CallbackParams query) {
        log.info("product message:{}", JSON.toJSONString(query));
        return Result.success(Boolean.TRUE);
    }
}
package com.cj.cn.constant.callback.domain;

import lombok.Data;

/**
 * @author : kay
 */
@Data
public class CallbackParams {
    private String messageId;
    private String type;
    private Object params;
}
package com.cj.cn.constant.callback.domain;

import lombok.Getter;
import org.springframework.util.StringUtils;

/**
 * @author : kay
 */
@Getter
public enum CallbackBusinessTypeEnum {
    PRODUCT,
    VARIANT,
    STOCK;

    public static CallbackBusinessTypeEnum create(String name) {
        if (!StringUtils.isEmpty(name)) {
            for (CallbackBusinessTypeEnum typeEnum: CallbackBusinessTypeEnum.values()) {
                if (typeEnum.name().equals(name.toUpperCase())) {
                    return typeEnum;
                }
            }
        }
        return null;
    }
}