Webhooks
Webhooks介绍
Webhooks是用户在操作 Midasbuy 的过程中，从 Midasbuy发起到到开发者服务器到调用。Webhooks提供一个用户购买流程中，和开发者服务器实时交互的机会。开发者可以根据用户商品信息进行进一步的处理，这些处理包括限制用户购买，给用户推荐某一个商品等。
目前Midasbuy 完成了基础的用户验证，商品验证，订单通知等能力，后续会进一步扩展 webhooks 能力，方便Midasbuy 和开发者配合一起给用户提供更好的体验。
接收处理
对于Webhooks的通知响应，遵循以下约定：
| 接收结果 | HTTP Code 约定 | 应答报文格式约定 |
|---|---|---|
| 接收成功 | 200 | processed设置为true |
| 接收失败 | 500 | processed设置为false |
针对 500 的错误 同步事件和异步事件有不同的处理方式
- 同步事件
终止流程，提示用户处理异常，需要重试。
- 异步事件
开发者服务器出现超时或者返回错误的情况下，Midasbuy会进行重试，重试的时间间隔策略是 1s,1m,10m,30m,1h,6h,12h,24h,168h
验证签名
Midas会在回调的HTTP头部中包括回调报文的签名。商户必须验证回调的签名，以确保回调是由Midas发送。
构造验签名串
首先，商户先从应答中获取以下信息：
-
HTTP头'Txgw-Timestamp' 中的应答时间戳。
-
HTTP头'Txgw-Nonce' 中的应答随机串
-
应答主体（response Body）
然后，请按照以下规则构造应答的验签名串。签名串共有三行，行尾以\n结束，包括最后一行。\n为换行符（ASCII编码值为0x0A）。若应答报文主体为空（如HTTP状态码为204 No Content），最后一行仅为一个\n换行符。
应答时间 戳\n
应答随机串\n
应答报文主体\n
如某个应答的HTTP报文为：
HTTP/1.1 200 OK
Server: nginx
Date: Tue, 02 Apr 2019 12:59:40 GMT
Content-Type: application/json; charset=utf-8
Content-Length: 2204
Connection: keep-alive
Keep-Alive: timeout=8
Content-Language: zh-CN
Request-ID: e2762b10-b6b9-5108-a42c-16fe2422fc8a
Txgw-Nonce: NONCE1234567890
Txgw-Signature: iRwHQ5FNt3KFv5nR0a7VFvFoGCCJA4ea330+Nb1LsBODDxmnNfz+/AaV/3QvF1nODzCDtwIo+1fMZlvcYVfKzldVYMi9uXp2crY116RxHnU5L2OcvM/IIudvZBUSOxDiaWPH79VO6+9dlccAKZ8eP2Zu9Svd9F95RWAaG/g72cIQDGmf7nyqAOopy1dz4Q/ZF7/1EsBlvPo5LyY521DCnbEq80FGf0nCR5vDplfV4PoYaI0jZ+qcHSB4hc1FOIIizcecI28sR22af0boO3F4Q98+jLRXxEyhYY/loijVkv6N+ZcEWs6C1ksy80a9/VyoxUhBP2O9HOPPcDwd4I/fOA==
Txgw-Timestamp: 1725519185
Cache-Control: no-cache, must-revalidate
{"id":"WEBHOOK240929CBXLYDCHMKXXE","create_time":"2024-09-18T14:40:09+08:00","update_time":"2024-09-18T14:40:09+08:00","resource":{"app_id":"145000000","user_id":"user_id1","server_id":"1"},"resource_type":"RESOURCE_TYPE_USER","resource_version":"1.0","event_version":"1.0","event_type":"USER_VALIDATE"}
则验签名串为
1725519185
NONCE1234567890
{\"id\":\"WEBHOOK240929CBXLYDCHMKXXE\",\"create_time\":\"2024-09-18T14:40:09+08:00\",\"update_time\":\"2024-09-18T14:40:09+08:00\",\"resource\":{\"app_id\":\"145000000\",\"user_id\":\"user_id1\",\"server_id\":\"1\"},\"resource_type\":\"RESOURCE_TYPE_USER\",\"resource_version\":\"1.0\",\"event_version\":\"1.0\",\"event_type\":\"USER_VALIDATE\"}
获取应答签名
Midas的应答签名通过HTTP头'Txgw-Signature'传递。（注意，示例因为排版可能存在换行，实际数据应在一行）
Txgw-Signature: nSbn5D/8NOhby7hoxDp7Ma+VnqSQm6K7/Pe6hXhjGV+NcmYkunJiovF+c87oaFua+W2tAuquyH6SZxLZ/FjKcG6GhhrlpuJnyb0dUfQ6UiehwSKs0omy1/wEb/ygwj4AFJZts1z5B0s95ErX4rk6H51FTy4akOjmr6XSgeLvz1tYzcKV6aZk1N66fbRJAozNn148T32JrWY2I5RYR7byLX9c/sHxiBD+6L93/Zj+KLE5ub95iBc9M+V7zsvs/MplME30Ks+JDyg29HCkZ7tSS25VzeCDxovGNMZ5MmDq4xQSYC6fH9qO41GP9E1iakKdt1V+6zyI52Z6/7h3FPjeeA==
对Txgw-Signature的字段值使用Base64进行解码，得到应答签名。
某些代理服务器或CDN服务提供商，转发时会“过滤“Midas扩展的HTTP头，导致应用层无法取到Midas的签名信息。商户遇到这种情况时，建议尝试调整代理服务器配置，或者通过直连的方式访问Midas的服务器和接收通知。