> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thedecard.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook 配置

> 说明如何配置 Webhook 地址、验证 HMAC 签名、快速返回成功响应并安全处理重试事件。

## 📄 正文

无论您是交易所、钱包还是平台方，都可以通过 Webhook 把 DCS 的卡片生命周期、交易授权、KYC 与工单等关键事件实时同步到自有系统，免去轮询查询的开销。DCS 作为持牌发卡机构，对每一条 Webhook 都附带签名，您只需校验签名即可确认事件确实来自 DCS。

本页讲两件事：**如何让 DCS 把事件推送到您的回调地址**（配置 + 白名单），以及**如何校验每条推送的真实性**（HMAC 签名）。事件类型与各事件的字段结构，请见[事件与数据结构](./events-and-schema)。

## 一、配置回调地址

<Warning>
  **谁做**：当前 Webhook 配置由 **DCS** 代为完成，接入机构暂无自助配置接口。请通过对接群或商务联系人提供以下信息。
</Warning>

接入机构需要向 DCS 提供两类回调地址：

| 地址           | 用途     | 推送内容                               |
| ------------ | ------ | ---------------------------------- |
| `webhookUrl` | 业务事件通知 | 卡订单状态、卡状态、KYC 工单、意图工单、授权结果（异步）     |
| `authUrl`    | 授权转发通知 | 实时授权请求（同步等待接入机构返回 Approve/Decline） |

> `authUrl` 用于合作伙伴自管模式下的**实时决策**，采用 RSA 双向签名加密，与本页的业务 Webhook（HMAC 签名）是两条独立通道。`authUrl` 的安全机制见[实时授权](../transactions/authorization)，回调地址与公钥的提供流程见[前置准备](../../getting-started/first-steps)。

### 回调地址要求

* 必须使用 `https`，且解析到**公网可达**的 IP；
* 需能在 DCS 的 Webhook **白名单**中登记——请同时向 DCS 提供您的**网络出口地址**（沙盒与生产分别提供）；
* 建议对外暴露一个**稳定、长期**的路径，避免频繁变更导致漏推。

<Warning>
  **谁做（接入机构）**：DCS 有 Webhook 白名单机制。沙盒与生产是两套独立配置，请分别提交地址，避免上线时漏配。
</Warning>

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

为确保通信安全，DCS 在**每条** Webhook 请求的 Header 中附带 `X-Signature`。该签名由 `HmacSHA256` 算法生成，密钥为您的 `secretKey`。接入机构在处理消息体前，必须用同样的算法对收到的**原始消息体**重新计算签名，并与 `X-Signature` 比对一致，才能确认请求真实、未被篡改。

### 请求头

| Header         | 说明                                   |
| -------------- | ------------------------------------ |
| `X-Signature`  | DCS 对原始消息体计算的 HMAC-SHA256 签名（Hex 编码） |
| `Content-Type` | 固定 `application/json`                |

<Warning>
  **务必对原始字节计算**：HMAC 必须基于 DCS 发送的**原始消息体字符串**计算。若先把 JSON 解析再重新生成，字段顺序、空格、转义可能发生变化，导致签名不一致、校验失败。请在解析**之前**先读取并缓存原始 body 用于验签。DCS 发送的报文为紧凑 JSON，各层级字段按完整字段名字典序排列，且后续可能新增字段——只要基于原始报文验签，均不受影响，详见[事件与数据结构 · 注意事项](./events-and-schema#注意事项)。
</Warning>

### 校验示例

DCS 官方提供的 Java 示例（计算消息体的 HMAC-SHA256）：

```java theme={null}
import org.apache.commons.codec.binary.Hex;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;

class HmacSignature {

    public static void main(String[] args) throws NoSuchAlgorithmException, InvalidKeyException {
        String secretKey = "secret_key";
        String webhookPayloadStr = "webhook_Payload_Str"; // 收到的原始消息体字符串
        byte[] hmacSha256;
        SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
        Mac mac = Mac.getInstance("HmacSHA256");
        mac.init(secretKeySpec);
        hmacSha256 = mac.doFinal(webhookPayloadStr.getBytes());
        // 与请求头 X-Signature 比对
        System.out.println(Hex.encodeHexString(hmacSha256));
    }
}
```

校验逻辑：`Hex(HmacSHA256(secretKey, 原始消息体))` 与 `X-Signature` **逐字符相等**则通过。建议使用恒定时间比较（constant-time compare），避免时序侧信道。

> `secretKey` 与 `apiKey` 同源，是 DCS 为接入机构分配的接入凭证。生产环境的安全提取流程见[接入鉴权](../../integration-resources/authentication)。请将 `secretKey` 视为机密，仅在服务端持有，切勿下发到前端或客户端。

## 三、响应与消费约定

为保证事件不丢、不重复处理，建议接入机构遵循以下约定：

| 项目   | 约定                        | 说明                                              |
| ---- | ------------------------- | ----------------------------------------------- |
| 成功应答 | 返回 HTTP `200`（2xx 均按成功处理） | 收到即先快速应答，再异步处理业务逻辑，避免超时                         |
| 幂等去重 | 以 `webhookId` 为键          | 同一事件可能被重复推送，处理前先按 `webhookId` 判重                |
| 失败重推 | 通用事件最多 3 次                | 由定时任务驱动，退避间隔随任务配置；实时 `AUTHORISATION` 不重试，超时直接拒绝 |
| 乱序到达 | 以 `notificationTime` 排序   | 网络与重推可能导致事件乱序，请用消息体内时间字段还原真实顺序                  |

> `webhookId` 与 `notificationTime` 等公共字段含义见[事件与数据结构](./events-and-schema#公共消息结构)。

<Warning>
  **避免返回 HTML/纯文本错误页**：处理失败时也应返回结构化响应（或 `2xx` 后异步重试），便于排障与重推追踪。
</Warning>

## 下一步

签名校验通过后，请前往[事件与数据结构](./events-and-schema)，根据 `webhookType` 解析各事件的 `data` 字段，并接入您的业务处理逻辑。