# 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",
    "messageType": "UPDATE",
    "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	Data Type	string	Y	20	PRODUCT
messageType	Message type	string	Y	15	INSERT、UPDATE、DELETE
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	status:2-Off sale, 3-On Sale
- fields	fields list	list	Y	5

Product Status

ProductStatus	Description
2	Off sale
3	On Sale

# Inbound message for Variant

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "VARIANT",
    "messageType": "UPDATE",
    "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	50	Message Id
type	Data Type	string	Y	20	VARIANT
messageType	Message Type	string	Y	15	INSERT、UPDATE、DELETE
params		object	Y
- vid	variant Id	string	Y	50
- variantName	variant name	string	Y	200
- variantWeight	variant weight, unit:g	int	Y
- variantLength	variant length, unit:mm	int	Y
- variantWidth	variant width, unit:mm	int	Y
- variantHeight	variant height, unit:mm	int	Y
- variantImage	variant image	string	Y	200
- variantSku	variant sku	string	Y	200
- variantKey	variant key	string	Y	200
- variantSellPrice	variant sell price, USD	double	Y
- variantStatus	variant status	int	Y	5
- variantValue1	variant value1	string	Y	100
- variantValue2	variant value2	string	Y	100
- variantValue3	variant value3	string	Y	100
- fields	fields list	list	Y	5

Variant Status

variantStatus	Description
0	Off sale
1	On sale

# Stock Message

{
    "messageId": "ca72a4834cd14b9588e88ce206f614a0",
    "type": "STOCK",
    "messageType": "UPDATE",
    "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",
    "messageType": "UPDATE",
    "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
messageId	Message id	string	Y	50	Message Id
type	Data Type	string	Y	20	ORDER
messageType	Message Type	string	Y	15	INSERT、UPDATE、DELETE、ORDER_CONNNECTED: This type requires special attention：The product has been re-associated in the CJ system, and the order status has been updated from incomplete to complete. At this point, The actual CJ order id is returned in this message.
params		object	Y
- 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
- trackingUrl	tracking URL	string	N	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",
    "messageType": "UPDATE",
    "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	Required	Length	Note
messageId	Message id	string	Y	50	Message Id
type	Data Type	string	Y	20	ORDERSPLIT
messageType	Message Type	string	Y	15	INSERT、UPDATE、DELETE
params		Object	Y
- originalOrderId	Original CJ order id	string	N	200
- orderSplitTime	Order Split Date	string	N	200
- splitOrderList	Order List	Order[]	N
- - orderCode	CJ order id	string	N	200
- - createAt	Create date	string	N	200
- - orderStatus	Order status	int	N	11
- - productList	Product Information List	Product[]	N	200
- - - productCode	product code	string	N	200
- - - vid	Variant id	string	N	200
- - - quantity	Quantity	int	N	10
- - - sku	Sku	string	N	50

# Source product creation result

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "SOURCINGCREATE",
    "messageType": "UPDATE",
    "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"
    }
}

返回字段	字段意思	字段类型	Required	长度	备注
messageId	Message id	string	Y	50	Message Id
type	Data Type	string	Y	20	ORDERSPLIT
messageType	Message Type	string	Y	15	INSERT、UPDATE、DELETE
params		Object	Y
- cjProductId	CJ product id	string	N	100
- cjVariantId	CJ variant id	string	N	100
- cjVariantSku	CJ variant sku	string	N	50
- cjSourcingId	CJ sourcing Id	string	N	50
- status	status	string	N	20
- failReason	fail reason	string	N	20
- createDate	create date	String	N	50

# Logistics message

{
    "messageId": "7cceede817dc47ed9748328b64353c5c",
    "type": "LOGISTIC",
    "messageType": "UPDATE",
    "openId": 12312,
     "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\"}]"
    }
}

Parameter	Definition	Type	Required	Length	Note
messageId	Message Id	string	Y	200	Message Id
type	Data Type	string	Y	200	LOGISTIC
messageType	Message Type	string	Y	15	INSERT、UPDATE、DELETE
params		object	Y
- orderId	CJ order id	string	Y	200	210823100016290555
- logisticName	logistic name	string	Y	200	CJPacket Ordinary
- trackingNumber	tracking number	string	Y	200	number12345678
- trackingUrl	tracking URL	string	N	200
- trackingStatus	tracking status	int	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;
    }
}

← Practical Tool Sandbox →