9.1 KiB
回调(Webhook)
1. 定位
三方仓的回调是仓方主动推送到商户配置的地址。SDK 的职责只有两件事:
- 验签
- 解析成统一出参
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。