Webhook 配置 - DCS Technical Documentation

📄 正文

企业卡的组织开户、员工创建、建卡、交易与入金都是异步的，终态由平台在事件发生时主动推送到您登记的回调地址，您不必轮询。接收端只需实现一个接口——所有事件共用同一套信封，读 webhookType 再解析 data 即可。事件全集与各事件的 data 结构见事件与数据结构。

一、登记回调地址

回调地址由平台运营为您配置，没有自助修改接口，需变更请联系对接人。沙盒与生产是两套独立配置，须分别登记。

未配置回调地址时，需要您参与的链路会直接失败——3DS 挑战无法转发给您，交易会被拒绝。走 OOB 或 otpSendMode=ENTERPRISE 发码前，必须先把回调地址配好。

回调地址要求

要求	说明
协议	必须是 HTTPS，证书须可公网校验
方法	接收 `POST`，请求体为 JSON
响应	返回 HTTP `2xx` 即视为投递成功，平台不解析响应体
时延	尽快返回——请先落库再异步处理业务，不要在回调里做长耗时操作
幂等	同一 `webhookId` 可能被推送多次，须按它去重；去重后仍返回 `2xx`

二、校验签名（HMAC-SHA256）

每一条推送都带 X-Signature。签名算法是：

X-Signature = Hex( HMAC-SHA256( SK, sortedCompactJson(整个 payload) ) )

SK 是平台为您单独下发的 Webhook 签名密钥，按入驻方隔离，与 API 请求签名的密钥不是同一把。

请求头

头	说明
`X-Signature`	签名值，十六进制小写
`Accept`	`application/json`

事件类型、时间戳与 ID 全部在请求体里，不进请求头。

不能直接对原始字节验签。 sortedCompactJson 的含义是：把 payload 所有层级的字段按字段名字典序排序，再去掉空白做紧凑序列化。您必须用同样的方式重新序列化后再比对，否则签名一定不匹配。

校验示例

import hmac, hashlib, json

def sorted_compact_json(obj):
    # 所有层级按字段名字典序排序 + 去空白紧凑序列化
    return json.dumps(obj, sort_keys=True, separators=(',', ':'), ensure_ascii=False)

def verify(payload_dict: dict, header_signature: str, sk: str) -> bool:
    body = sorted_compact_json(payload_dict).encode('utf-8')
    expected = hmac.new(sk.encode('utf-8'), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header_signature.lower())

验签失败请直接丢弃并告警，不要按业务处理。

三、投递、重试与顺序

项	约定
成功判定	HTTP `2xx` 即成功，不解析响应体
重试触发	非 `2xx` 或超时
重试节奏	落库待重投，定时任务约每分钟扫描一轮；重投上限 3 次、间隔约 1 分钟、无指数退避
总窗口	首发加重投合计最多 4 次，约 3 分钟内结束
仍失败	平台侧告警并人工跟进
幂等键	`webhookId` 全局唯一，同一事件的所有重试复用同一个
顺序	不保证有序。请以 `webhookId`（雪花 ID，单调递增）加资源当前状态判断先后，不要假定到达顺序
兜底	窗口内没收到，用对应的查询接口对账

重试窗口只有约 3 分钟。接收服务停机超过这个窗口就会漏事件，必须用查询接口做兜底对账，不能只依赖 Webhook。

下一步

事件全集、信封字段与各事件的 data 结构：事件与数据结构
3DS 挑战的接收与回传：3DS 挑战

​📄 正文

​一、登记回调地址

​回调地址要求

​二、校验签名（HMAC-SHA256）

​请求头

​校验示例

​三、投递、重试与顺序

​下一步

📄 正文

一、登记回调地址

回调地址要求

二、校验签名（HMAC-SHA256）

请求头

校验示例

三、投递、重试与顺序

下一步