异步通知 (Notify URL) 系统如何迁移到 Webhooks 的方法?

更新于:2017年11月30日 19:22:15

随着支付场景日益丰富,Ping++ 推出了 Webhooks 作为新的通知系统,以更替原有的异步通知系统。相比于异步通知系统, Webhooks 具有以下优势:

为什么要使用 Webhooks

  • Webhooks拥有消息签名机制,商户可以通过签名验证通知消息的真实性。

  • Webhooks 支持在不同的环境(Test/Live)下配置多个 URL,商户可以在不同环境中接收 Webhooks 通知。    

  • Webhooks 只发送 Event 对象,简化了用户需要处理的对象类型,原有的如 ChargeRefund对象等作为 Event 对象的类型包含在 Event 对象内。

  • Webhooks 的 Event 包含了丰富的事件类型供商户选择,商户可以选择性地接收相应类型的通知,便于区分处理。

  • Webhooks支持配置指定的 App 接收通知,增加了配置的灵活性,同时也方便用户进行日/周/月交易统计。

  • 联调工具已支持Webhooks 调试。

  • Webhooks支持根据 Event ID 查询指定的事件,也可以查询事件的列表,方便商户可以查询自己想要的 Webhooks 通知。

为了保证更好的服务,Ping++ 建议使用异步通知 Notify URL 的商户尽早迁移用 Webhooks。

如何迁移到 Webhooks

Step1:在管理平台配置 Webhooks

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

配置字段含义分别如下:

  1. 1、[Test/Live] 代表该 URL 是在 Live 还是 Test 环境下接收的通知

  2. 2、[接收 URL] 填写 URL 作为 webhoooks 接收地址。

  1. 3、[通知事件] 配置的是事件类型,选择需要接收的事件类型。

  2. 4、[编辑]用于更新已配置的 webhooks 的事件类型。

  3. 5、[测试]用于 webhooks 测试功能,可以模拟 webhooks 向你配置的地址发送通知,用于调试。

  4. 6、[删除]可删除整条 webhooks url 配置。

Step2:在服务器接收 Webhooks

在管理平台完成了配置以后,需要到配置的地址去监听并且接收 Webhooks 通知。Webhooks 通知以 POST 方式发送的一个 JSON 字符串,内容是 Event 对象。

商户接收到了 Webhooks 后,可根据 object 字段验证接收到的是否为 Event 对象。

  • Event 对象的字段 type 指的是事件类型,商户根据该字段值判断是不是所需要接收的事件类型。

  • Event 对象中的 data 字段表示绑定在事件上的数据对象,里面的 object 字段包含了数据对象的具体内容。比如商户接收的事件类型是 charge.succeeded,那么 data 里面的 object 字段则为 Charge 对象。

商户监听并且接收到 Webhooks 通知以后,需要给 Ping++ 服务器状态 2xx 作为回复,否则请返回状态码 500。若返回状态码不是 2xx,Ping++ 服务器会在 25 小时内向你的服务器进行多次重发,最多 10 次,时间规则跟异步通知相同。

Step3:验证 Webhooks 通知

Ping++ 的 Webhooks 通知包含了签名字段,可以使用该签名验证 Webhooks 通知的合法性。签名放置在 header 的自定义字段 x-pingplusplus-signature 中(注意:headers 字段的 key 应该忽略大小写)。签名用 RSA 私钥对 Webhooks 通知使用 RSA-SHA256 算法进行签名,以 base64 格式输出。

Ping++ 在管理平台中提供了 Ping++ 公钥,供验证签名,该公钥信息可在公司签约完成后,在管理平台的 右上角公司名称->企业面板->开发参数 中获取。验证签名需要以下两步:

  1. 从 header 取出签名字段(headers 字段的 key 应该忽略大小写)并对其进行 base64 解码。

  2. 把 Webhooks 通知、Ping++ 管理平台提供的 Ping++ 公钥、 和 base64 解码后的签名三者一同放入 RSA 的签名函数中进行非对称的签名运算,来判断签名是否验证通过。

Step4:停掉旧的 Notify URL 

blob.png

在完成 webhooks 的配置并且正常接收验证通过 webhooks 以后的 25 小时之后,再关闭 notify url 。关闭 notify url 只需要登陆管理平台,点击应用配置并且删除 notify url 即可。(注意:删除 notify url 之后的 25 小时之内可能还是会收到通知,只要满足配置完成 webhooks 已达到 25 小时,即可忽略这些 notify url 的通知)

    您需要登录后才可以回复