Webhook 集成

说明： Webhook 是一种在特定事件发生时自动向指定 URL 发送 HTTP POST 请求的机制。通过使用 Webhook，您的应用程序可以实时接收有关特定事件的通知，例如数据更新、状态更改等。

如何使用 Webhook?

要使用 Webhook，您需要执行以下步骤：

1. 注册 Webhook URL：在您的应用程序中创建一个 URL，用于接收 Webhook 请求。
2. 配置 Webhook：在触发特定事件时，配置相关服务或应用程序以向您提供的 Webhook URL 发送 HTTP POST 请求。本版本 将URL传入支付接口的webhookUrl字段中，当支付状态发生变化时，支付接口会向该URL发送通知。
3. 处理 Webhook 请求：在您的应用程序中编写代码来处理接收到的 Webhook 请求，执行相应的操作或逻辑。

Webhook 请求参数

参数名称	类型	出现要求	描述
event	string	R	事件类型,定义请见"附录B Webhook事件类型说明"
data	string	R	数据,具体参数由事件类型决定,定义请见"附录C 已支持的事件类型"

下面是一个示例 Webhook 请求的格式：

• 入金事件

{
  "event": "DEPOSIT_EVENT",
  "data": {
    "trackingId": "123",
    "status": 1,
    "amount": 100
  }
}

• 出金事件

{
  "event": "WITHDRAWAL_EVENT",
  "data": {
    "trackingId": "123",
    "status": 1,
    "amount": 100,
    "stayReason": "审核中"
  }
}

Webhook 响应

返回字符串:Webhook received 除此之外任何情况都视为未送达

Webhook 接口实现例子

@PostMapping("/webhook")
public String handleWebhookRequest(@RequestBody String payload, @RequestHeader("X-Signature") String receivedSignature) {
    log.info("回调参数：{},回调签名：{}", payload, receivedSignature);
    String calculatedSignature = calculateHMAC(payload, secretKey);
    if (calculatedSignature.equals(receivedSignature)) {
        // 签名验证成功，继续处理请求

        // 解析请求参数
//          JSONObject jsonObject = JSONUtil.parseObj(payload);
//          String eventType = jsonObject.getStr("event");
//          JSONObject data = jsonObject.getJSONObject("data");
//          String trackingId = data.getStr("trackingId");
      // 调用入金或出金查询接口 确认通知是否有效
        return "Webhook received";
    } else {
        // 签名验证失败，拒绝请求或记录日志
        log.info("回调生成签名：{}，回调签名：{}, 回调验签失败", calculatedSignature, receivedSignature);
        return "Unauthorized";
    }
}

public static String calculateHMAC(String data, String secretKey) {
    try {
        SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(StandardCharsets.UTF_8), HMAC_SHA_512);
        Mac mac = Mac.getInstance(HMAC_SHA_512);
        mac.init(secretKeySpec);
        byte[] rawHmac = mac.doFinal(data.getBytes(StandardCharsets.UTF_8));
        return Base64.getEncoder().encodeToString(rawHmac);
    } catch (NoSuchAlgorithmException | InvalidKeyException e) {
        throw new RuntimeException("Failed to calculate HMAC: " + e.getMessage(), e);
    }
}

以下是一个 Node.js 版本的 Webhook 处理和 HMAC 计算的示例：

const express = require('express');
const crypto = require('crypto');
const bodyParser = require('body-parser');

const app = express();
app.use(bodyParser.text());

const secretKey = 'your_secret_key';  // 替换为你的秘钥

app.post('/webhook', (req, res) => {
    const payload = req.body;
    const receivedSignature = req.header('X-Signature');

    console.log(`Payload: ${payload}, Received Signature: ${receivedSignature}`);

    const calculatedSignature = calculateHMAC(payload, secretKey);

    if (calculatedSignature === receivedSignature) {
        // 签名验证成功，处理请求

        // 解析请求参数
        // let jsonObject = JSON.parse(payload);
        // let eventType = jsonObject.event;
        // let data = jsonObject.data;
        // let trackingId = data.trackingId;
        // 调用充值或提现查询接口，确认通知是否有效

        res.send('Webhook received');
    } else {
        // 签名验证失败，拒绝请求或记录日志
        console.log(`Calculated Signature: ${calculatedSignature}, Received Signature: ${receivedSignature}, Webhook signature error`);
        res.status(401).send('Unauthorized');
    }
});

function calculateHMAC(data, secretKey) {
    const hmac = crypto.createHmac('sha512', secretKey);
    const dataHmac = hmac.update(data);
    const hmacDigest = dataHmac.digest('base64');
    return hmacDigest;
}

app.listen(3000, () => console.log('Server is listening on port 3000'));

这个示例使用了 Express.js，它是一个非常流行的 Node.js Web 框架。这段代码创建了一个 Express.js 服务器，并监听 /webhook 路径的 POST 请求。当接收到请求时，它会计算 HMAC 并与请求头中的 X-Signature 进行比较。如果 HMAC 相符，它返回 "Webhook received"，否则返回 HTTP 401 错误和 "Unauthorized" 消息。

请注意，你需要使用 npm 安装 express 和 body-parser 这两个依赖：

npm install express body-parser

安全性注意事项

在使用 Webhook 时，务必考虑安全性问题，以防止未经授权的访问或数据泄露。以下是一些安全性建议：

• 使用 HTTPS 协议保护 Webhook 通信。
• 验证接收到的 Webhook 请求的来源和内容，以确保其合法性。(接收通知后,调用入金查询或出金查询接口获取数据，对比数据是否一致)

附录B Webhook事件类型说明

事件类型	描述
DEPOSIT_EVENT	入金事件
WITHDRAWAL_EVENT	出金事件

附录C 已支持的事件类型

• DEPOSIT_EVENT

  参数名称	类型	出现要求	描述
  trackingId	string	R	跟踪id
  status	int	R	入金状态
  amount	int	R	入金金额

• WITHDRAWAL_EVENT

  参数名称	类型	出现要求	描述
  trackingId	string	R	跟踪id
  status	int	R	出金状态
  amount	int	R	出金金额
  stayReason	string	O	出金出现异常的原因