📄 正文
无论您是交易所、钱包还是平台方，都可以通过 Webhook 把 DCS 的卡片生命周期、交易授权、KYC 与工单等关键事件实时同步到自有系统，免去轮询查询的开销。DCS 作为持牌发卡机构，对每一条 Webhook 都附带签名，您只需校验签名即可确认事件确实来自 DCS。
本页讲两件事：如何让 DCS 把事件推送到您的回调地址（配置 + 白名单），以及如何校验每条推送的真实性（HMAC 签名）。事件类型与各事件的字段结构，请见事件与数据结构。
一、配置回调地址
谁做：当前 Webhook 配置由 DCS 代为完成，接入机构暂无自助配置接口。请通过对接群或商务联系人提供以下信息。
authUrl 用于合作伙伴自管模式下的实时决策，采用 RSA 双向签名加密，与本页的业务 Webhook（HMAC 签名）是两条独立通道。authUrl 的安全机制见实时授权，回调地址与公钥的提供流程见前置准备。
回调地址要求
- 必须使用
https，且解析到公网可达的 IP；
- 需能在 DCS 的 Webhook 白名单中登记——请同时向 DCS 提供您的网络出口地址（沙盒与生产分别提供）；
- 建议对外暴露一个稳定、长期的路径，避免频繁变更导致漏推。
谁做（接入机构）：DCS 有 Webhook 白名单机制。沙盒与生产是两套独立配置，请分别提交地址，避免上线时漏配。
二、校验签名（HMAC-SHA256）
为确保通信安全，DCS 在每条 Webhook 请求的 Header 中附带 X-Signature。该签名由 HmacSHA256 算法生成，密钥为您的 secretKey。接入机构在处理消息体前，必须用同样的算法对收到的原始消息体重新计算签名，并与 X-Signature 比对一致，才能确认请求真实、未被篡改。
请求头
务必对原始字节计算：HMAC 必须基于 DCS 发送的原始消息体字符串计算。若先把 JSON 解析再重新生成，字段顺序、空格、转义可能发生变化，导致签名不一致、校验失败。请在解析之前先读取并缓存原始 body 用于验签。DCS 发送的报文为紧凑 JSON，各层级字段按完整字段名字典序排列，且后续可能新增字段——只要基于原始报文验签，均不受影响，详见事件与数据结构 · 注意事项。 校验示例
DCS 官方提供的 Java 示例（计算消息体的 HMAC-SHA256）：
校验逻辑：Hex(HmacSHA256(secretKey, 原始消息体)) 与 X-Signature 逐字符相等则通过。建议使用恒定时间比较（constant-time compare），避免时序侧信道。
secretKey 与 apiKey 同源，是 DCS 为接入机构分配的接入凭证。生产环境的安全提取流程见接入鉴权。请将 secretKey 视为机密，仅在服务端持有，切勿下发到前端或客户端。
三、响应与消费约定
为保证事件不丢、不重复处理，建议接入机构遵循以下约定：
webhookId 与 notificationTime 等公共字段含义见事件与数据结构。
避免返回 HTML/纯文本错误页：处理失败时也应返回结构化响应（或 2xx 后异步重试），便于排障与重推追踪。
下一步
签名校验通过后，请前往事件与数据结构，根据 webhookType 解析各事件的 data 字段，并接入您的业务处理逻辑。
