Webhooks 的适用场景

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

配置 Webhooks

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

1. Webhooks 地址

   你服务器接收 Ping++ Webhooks 通知的地址，需要根据 Webhooks 来更新订单状态。

2. Webhooks 的模式

   支持 Test 模式和 Live 模式，即事件中包含的数据内容可以源于测试环境也可以源于生产环境。需要在顶部进行 TEST / LIVE 模式进行切换后添加。

3. Webhooks 支持的事件

   当前 Webhooks 支持的事件类型详情请见：Webhooks 事件类型。

4. 查询 Webhooks 事件

   你可以通过 event 对象的 id 查询一个已创建的 Event 对象，详情请见API 文档。

5. 查询 Webhooks 事件列表

   你可以查询之前创建 Event 对象的一个列表，列表是按创建时间进行排序，总是将最新的 Event 对象显示在最前，详情请见 API 文档。

Webhooks 测试

用于测试你服务器的连通性以及你服务器是否正确返回 Ping++ 需要的服务器状态码以及签名验证的工具。

该工具在「Webhooks」配置的页面，点击 测试，然后选择 事件类型 并且点击「测试」按钮，Ping++ Webhooks 测试工具会向你配置的 Webhooks 地址主动发送你选择的事件内容，并且会记录你返回的服务器状态码以及 body 内容。注意 ：Ping++ 只根据你返回的服务器状态码来判断你是否接收成功，和你返回的 body 内容没有关系，另外当前 Webhooks 测试工具不支持自定义发送内容。

接收 Webhooks 通知

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

Webhooks 异常处理

在 Test 模式下，我们提供了模拟 Webhooks 通知异常功能：创建订单时，通过在 metadata 字段中上传 pingpp_tc 字段，例如： "metadata":{"pingpp_tc":"001"} 来模拟 Webhooks 通知延迟以及重发，字段详见 API 文档 。

你需要针对 Webhooks 延迟以及重复发送同一通知的情况进行处理，合理优化服务端接收 Webhooks 异步通知部分的逻辑。

注： 此功能仅在 Test 模式下有效，不影响 Live 环境的使用。

验证 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 里供参考，此处不再赘述。