Webhooks 使用指南

为了满足客户对不同事件的特定处理需求,Ping++ 推出了 Webhooks 功能,以更替原有的异步通知系统。点此查看 异步通知系统迁移到 Webhooks 的方法

Webhooks 的适用场景

为了便于客户系统或者第三方系统处理客户的交易信息,Ping++ 系统支持 Webhooks 功能,可以按照客户要求把特定的事件结果推送到指定的地址以便于客户做后续处理。目前支持的事件包括周期性交易汇总信息、支付结果、红包结果、企业转账结果和退款结果。如果你还需要其他类型事件,请联系我们。

配置 Webhooks

登录 Ping++ 管理平台,点击你创建的应用,点击左侧 Webhooks 选项。新建一个 Webhooks 事件的基本操作如下图所示,用户需要设置接收 Webhooks 事件的地址、模式和事件类型。

Webhooks Config

  1. Webhooks 地址 你服务器接收 Ping++ Webhooks 通知的地址,需要根据 Webhooks 来更新订单状态。
  2. Webhooks 的模式 支持 Test 模式和 Live 模式,即事件中包含的数据内容可以源于测试环境也可以源于生产环境。
  3. Webhooks 支持的事件 当前 Webhooks 支持 9 种事件类型,如下所示:
    • summary.daily.available 日汇总
    • summary.weekly.available 周汇总
    • summary.monthly.available 月汇总
    • charge.succeeded 支付成功
    • refund.succeeded 退款成功
    • transfer.succeeded 企业付款成功
    • red_envelope.sent 红包发送成功
    • red_envelope.received 红包领取成功
    • batch_transfer.succeeded 支付宝批量付款成功
    • customs.succeeded 报关成功
    • batch_refund.succeeded 批量退款成功
  4. 查询 Webhooks 事件 你可以通过 event 对象的 id 查询一个已创建的 Event 对象,详情请见API 文档
  5. 查询 Webhooks 事件列表 你可以查询之前创建 Event 对象的一个列表,列表是按创建时间进行排序,总是将最新的 Event 对象显示在最前,详情请见 API 文档

接收 Webhooks 通知

  1. Webhooks 是 Ping++ 和你服务器间的交互,不像页面跳转同步通知可以在页面上显示出来,这种交互方式是不可见的。
  2. Webhooks 通知是以 POST 形式发送的 JSON ,放在请求的 body 里,内容是 Event 对象。
  3. 你需要监听并接收 Webhooks 通知,接收到 Webhooks 后需要返回服务器状态码 2xx 表示接收成功,否则请返回状态码 500。具体接收的代码示例请根据你服务端的开发语言参考 Git 上的 DEMO
  4. 若返回的服务器状态码不是 2xx,Ping++ 服务器会在 25 小时内向你的服务器不断重发通知,最多 8 次。Webhooks 首次是即时推送,重试通知时间间隔为 5s、10s、2min、5min、10min、30min、1h、2h、6h、15h,直到你正确回复状态 2xx 或者超过最大重发次数,Ping++ 将不再发送。

验证 Webhooks 签名(可选)

为了进一步确保安全性, Ping++ Webhooks 提供了签名验证。你需要验证该通知是来自于 Ping++ 后再更新你的订单状态。

签名简介

Ping++ 的 Webhooks 通知包含了签名字段,可以使用该签名验证 Webhooks 通知的合法性。签名放置在 header 的自定义字段 x-pingplusplus-signature 中,签名用 RSA 私钥对 Webhooks 通知使用 RSA-SHA256 算法进行签名,以 base64 格式输出。

验证签名

Ping++ 在管理平台中提供了 RSA 公钥,供验证签名,该公钥具体获取路径:点击管理平台右上角公司名称->开发信息-> Ping++ 公钥。验证签名需要以下几步:

  1. 从 header 取出签名字段并对其进行 base64 解码。
  2. 获取 Webhooks 请求的原始数据。
  3. 将获取到的 Webhooks 通知、 Ping++ 管理平台提供的 RSA 公钥、和 base64 解码后的签名三者一同放入 RSA 的签名函数中进行非对称的签名运算,来判断签名是否验证通过。 Ping++ 提供了验证签名的 Demo ,放在 SDK 的 example 里供参考,我们在此不再赘述。

下一步联调工具