webhook说明

当业务处理完成后，有部分数据或信息需要进行审核、业务本身数据需要异步处理后再下发等情况时，平台会通过异步通知的方式，将数据下发给商户，商户需要做好相关的通知对接和己方的业务处理。

webhook后台配置

需要在商户端配置对应业务的通知地址（系统设置->api信息->Webhooks）

商户响应

商户收到回调请求后，需要在10秒内响应http状态码200，来表明已经处理成功无需再下发通知。
如果响应时间超过10秒或者http状态码非200，认为商户处理失败，将按 1 / 5 / 30 / 60 / 120 分钟间隔重复通知。

通知内容

公共请求头

请求头	说明
Webhook-MessageType	消息通知类型
Webhook-Timestamp	Unix 秒级时间戳
Webhook-Signature	签名

消息通知类型

请求头中的 Message-Type 字段可选值

枚举值(事件标识)	说明
CardBatch	卡任务通知
CardCreate	开卡成功
CardOrder	卡充退通知
CardStatus	卡状态变动通知
CardStatusOperate	销卡，解冻，解冻操作通知
CardTransaction	卡交易通知
BudgetTransfer	预算账户交易通知
BudgetActivate	预算账户激活成功

请求体

实际通知的数据、内容请参考webhook分类下的文档。

签名算法

请求头中的Webhook-Signature为本次请求数据的签名。 生成方式为

1. 使用.拼接 请求头中的消息通知类型、请求头中的Timestamp、请求体，即： data = "{Webhook-MessageType}.{Webhook-Timestamp}.{rawBody}"
   如Webhook-MessageType为 TYPE1
   Webhook-Timestamp为 12345698
   rawBody为 aaa
   则data = "TYPE1.12345698.aaa"

2. 使用merchant_secret，对data进行SHA256运算。
   HMAC-SHA256(data, merchant_secret)

验签代码示例

• golang

func checkSign(w http.ResponseWriter, r *http.Request) {
    secret := "xxx"

    bodyBytes, err := io.ReadAll(r.Body)
    defer r.Body.Close() // 必须关闭
    if err != nil {
            http.Error(w, "read body error", http.StatusInternalServerError)
            return
    }

    sign := r.Header.Get("Webhook-Signature")
    msgType := r.Header.Get("Webhook-MessageType")
    timestamp := r.Header.Get("Webhook-Timestamp")
    data := fmt.Sprintf("%s.%s.%s", msgType, timestamp, bodyBytes)

    h := hmac.New(sha256.New, []byte(secret))
    h.Write([]byte(data))
    signature := h.Sum(nil)
    verifySign := fmt.Sprintf("%x", signature)
   
    fmt.Println(verifySign == sign)
 }