You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

9.1 KiB

回调(Webhook)

1. 定位

三方仓的回调是仓方主动推送到商户配置的地址。SDK 的职责只有两件事:

  1. 验签
  2. 解析成统一出参

SDK 不监听端口、不做去重存储、不落库——这些是宿主的工作。

2. 完整链路

┌─────────┐  ① 推送到 OMS 配置的地址
│ 三方仓   │  POST /user/callback/yqn
└────┬────┘  Header: X-AppKey / X-Timestamp / X-Signature
     │       Body:   原始 JSON
     ▼
┌──────────────────────────────────────┐
│ OMS HTTP 入口                        │
│ @PostMapping("/user/callback/yqn")   │
│ String rawBody  ← 必须拿原文          │
└────┬─────────────────────────────────┘
     │  ② sdk.webhook(provider, secret, headers, rawBody, nowMillis)
     ▼
┌──────────────────────────────────────┐
│ WarehouseSdk.webhook                 │
│  1. 按 provider 找适配器(不需仓账户) │
│  2. 检查 WEBHOOK 能力位               │
│  3. adapter.verify(...)  验签失败直接抛│
│  4. adapter.parse(...)   验签通过才解析│
└────┬─────────────────────────────────┘
     │  ③ List<WarehouseCallback>
     ▼
┌──────────────────────────────────────┐
│ OMS 业务:按 eventType 分派落库       │
└──────────────────────────────────────┘

为什么需要单独的 sdk.webhook(...)

普通调用是 sdk.warehouses(warehouseCode, conn).xxx(),要先知道仓编码。

但回调进来时:

  • 只有 provider(由 OMS 的路由决定,如 /user/callback/yqn)
  • 没有 warehouseCode——仓编码在报文里,甚至报文可能不带
  • 不需要完整的 WarehouseConnection——验签只要 appSecret

所以入口只按 provider 分派,不查 WarehouseRepository。

3. 出参模型

WarehouseCallback
├── sourceProvider       // 哪家仓
├── eventType            // 统一枚举,按它分派
├── rawEventType         // 仓方原值,排查用
├── eventId              // 仓方给的事件 id(可能为 null)
├── rawStatus            // 仓方状态原值(需与 rawEventType 一起解释)
├── providerWarehouseCode // 仓方仓编码
├── providerOrderNo      // 仓方单据号
├── requestNo            // 我们下发的来源单号
├── occurredAt           // 变更时间
├── rawBody              // 原始报文(排查与回溯)
│
├── outbound   → 面单 / 出库载荷
├── returns    → 退货载荷
├── inbound    → 入库载荷
└── inventory  → 库存变动载荷

事件类型

WarehouseEventType 含义 载荷
LABEL_PURCHASED 面单购买成功 outbound
ORDER_STATUS_CHANGED 业务单据状态变更 无(看 rawStatus + rawEventType)
RETURN_INBOUND_COMPLETED 退货入库完成 returns
INVENTORY_CHANGED 库存变动(增量流水) inventory
UNKNOWN 无法识别 —

各载荷

OutboundPayload(面单)

trackingNumber / carrier / shippingMethodCode / deliverOrderNo

ReturnPayload

lines[] → lineId / providerSku / quantity / disposition / batchNo / batchParams

InventoryPayload

sku / inventoryType / overWarehouse / sourceNo / planNo / orderNo
providerOperationType   // 仓方单据类型码
inbound                 // Boolean:true 入库 / false 出库 / null 未知
quantity                // 恒为正,方向看 inbound

InboundPayload

receivedQuantity / cartonQuantity

4. 验签

运去哪算法

data      = appKey + "|" + timestamp + "|" + rawBody
signature = Base64(HmacSHA256(appSecret, data))

请求头:X-AppKey / X-Timestamp / X-Signature。

实现在 WebhookSignatures(core 通用)+ YqnLabelCallbackParser.verify(yqn)。

三个细节

① 恒定时间比较

// 不用 String.equals:提前返回会把「匹配了几位」泄漏成时间差
WebhookSignatures.constantTimeEquals(expected, actual)

② 时间戳窗口 5 分钟

WebhookSignatures.requireFreshTimestamp(timestampMillis, nowMillis, tolerance)

③ 头名大小写不敏感

不同网关会改写大小写,WebhookSignatures.header() 逐个忽略大小写比对。

5. 报文分派

运去哪不按路径区分回调——四种报文打同一个地址。适配器按报文特征分派:

含 processMode  → 退货入库完成(API 142)
含 opType       → 库存变动(API 150)
含 orderNoType  → 业务单据变动(API 154)
否则            → 面单购买成功(API 149)

风险:如果报文的值里恰好出现同名字面量,会误分派。目前接受这个风险,因为字段名都很独特。

6. 宿主要做什么

@RestController
public class WarehouseCallbackController {

    private final WarehouseSdk sdk;
    private final SecretProvider secrets;   // 按 provider 取 appKey/appSecret
    private final WarehouseWebhookDedupStore dedup;
    private final UnmatchedCallbackStore unmatched;

    @PostMapping("/user/callback/yqn")
    public ResponseEntity<Map<String, Object>> yqn(
            @RequestBody String rawBody,                     // ← 必须 String
            @RequestHeader Map<String, String> headers) {    // ← 原始头

        List<WarehouseCallback> callbacks;
        try {
            callbacks = sdk.webhook(
                    WarehouseProvider.YQN,
                    secrets.forProvider(WarehouseProvider.YQN),
                    headers,
                    rawBody,
                    System.currentTimeMillis());
        } catch (WarehouseWebhookVerificationException e) {
            // 验签失败:返回 4xx,不重试
            return ResponseEntity.badRequest().body(reply(400, "signature invalid"));
        }

        for (WarehouseCallback cb : callbacks) {
            // 去重:仓方可能重推
            String key = cb.eventId() != null ? cb.eventId() : cb.fingerprint();
            if (!dedup.claim(cb.sourceProvider().name(), key)) {
                continue;   // 重复事件,直接丢
            }
            try {
                dispatch(cb);
            } catch (Exception e) {
                dedup.release(cb.sourceProvider().name(), key);  // 失败放回,允许重投
                throw e;
            }
        }
        return ResponseEntity.ok(reply(200, "success"));
    }

    private void dispatch(WarehouseCallback cb) {
        switch (cb.eventType()) {
            case LABEL_PURCHASED:
                orderService.bindTracking(cb.requestNo(), cb.outbound());
                break;
            case ORDER_STATUS_CHANGED:
                // rawEventType = "ORDER_STATUS:<单据类型>",rawStatus = 状态码
                // 状态码含义随单据类型变化,必须成对解释
                orderService.advanceStatus(cb.providerOrderNo(), cb.rawEventType(), cb.rawStatus());
                break;
            case RETURN_INBOUND_COMPLETED:
                returnService.applyResult(cb.providerOrderNo(), cb.returns());
                break;
            case INVENTORY_CHANGED:
                // 增量流水,不是快照;inbound 可能为 null(方向未知)
                inventoryService.applyDelta(cb.inventory());
                break;
            default:
                unmatched.save(cb.sourceProvider().name(), null, cb.rawBody(), "unknown event");
        }
    }
}

7. 四个必须注意的点

① 必须用 @RequestBody String

如果先反序列化成对象、再转回 JSON,字段顺序或空白会变化,签名就对不上了。

② 验签失败要返回非成功

WarehouseWebhookVerificationException 抛出后不要吞掉。仓方需要知道被拒。

③ 响应的 code 值要跟仓方确认

运去哪文档写「code: 200 成功」,但示例里给的是 1。如果返回 200 而仓方认为失败,会无限重推。

④ inbound() 是三态

Boolean inbound = cb.inventory().inbound();
if (inbound == null) { /* 方向未知,留档人工处理 */ }

不能写成 if (!inbound) —— Boolean 为 null 时拆箱会 NPE。

8. 去重指纹

仓方没给 eventId 时用 fingerprint():

sourceProvider | eventType | providerOrderNo | requestNo | rawStatus | occurredAt

参与计算的字段都是同一事件重复推送时不变的。载荷内容不参与——里面可能有随推送变化的字段。

9. 未实现的仓

XincangAdapter 目前没有实现 WarehouseWebhookCapable,调用会抛 WarehouseUnsupportedCapabilityException。