概览

Webhook 将卡片、交易等状态变化推送到你的 HTTPS 端点。你的服务应快速确认接收，把耗时业务放入异步队列处理。

接入流程

1. 部署一个可公网访问的 HTTPS 接收地址。
2. 在开发者控制台创建 Webhook 配置并选择事件，立即安全保存创建时返回的密钥。
3. 使用密钥对原始请求体执行 HMAC-SHA256，并将结果转换为 Base64 编码。
4. 使用常量时间比较计算结果与请求头 x-wk-signature，验签失败时拒绝请求。
5. 返回成功状态后异步处理事件。
6. 使用事件 ID 去重，并保留原始请求用于审计。

Webhook 请求头

{
  "Content-Type": "application/json",
  "x-wk-signature": "9Bmm1+JFkNpv3Ea3xK+SjJuN3RP4frCjuTfiSUfJhTQ="
}

x-wk-signature 是平台根据本次请求的原始 payload 计算出的签名。HTTP 请求头名称不区分大小写。

事件 payload 示例

curl --request POST 'https://webhook.example.com/callback' \
  --header 'Content-Type: application/json' \
  --header 'x-wk-signature: 9Bmm1+JFkNpv3Ea3xK+SjJuN3RP4frCjuTfiSUfJhTQ=' \
  --data-raw '{
    "account_no": "260424******",
    "data": {
      "authorization_code": "ABC123",
      "billing_amount": "0.03",
      "billing_currency": "USD",
      "card_available_balance": "34.23",
      "card_id": "card_example_7dfkac0",
      "card_number": "493724******8867",
      "cardholder_id": "cardholder_example_6qsbg",
      "description": "3DS Fee",
      "fee_pass_through": "N",
      "merchant_data": [
        {
          "category_code": "5815",
          "city": "",
          "country": "GB",
          "name": "Example Merchant"
        }
      ],
      "original_transaction_id": "",
      "posted_time": "2026-09-02T13:55:03.034+08:00",
      "short_transaction_id": "T260902-EXAMPLE",
      "transaction_amount": "0.03",
      "transaction_currency": "USD",
      "transaction_fee": "0",
      "transaction_fee_currency": "",
      "transaction_id": "9e3e332a-4222-4781-aabf-example0001",
      "transaction_status": "APPROVED",
      "transaction_time": "2026-09-02T13:55:03.034+08:00",
      "transaction_type": "AUTHORIZATION",
      "wallet_type": ""
    },
    "event_id": "8c937620-5a13-4e73-9a2e-example0002",
    "event_type": "card.transaction.authorization",
    "timestamp": "2026-09-02T05:55:03Z"
  }'

接收端完成验签并将事件成功后，应返回 HTTP 200。验签实现与重试规则见验签与重试。