Webhook（网络钩子）

Hipay 会通过 Webhook 向你的应用程序通知账户发生的各类事件。针对 Hipay 未主动通知的事件（如付款已完成、虚拟账户已创建并付款、发票已过期等），请配置 Webhook。

配置

你需要在系统中提供一个端点以接收我们的 Webhook 通知。Webhook 通知将通过 POST 请求发送至你设置的 Webhook 地址，请在 Webhook 设置中配置该地址。测试期间，你可使用 ngrok 等工具让端点能够接收 Webhook。

投递尝试与重试机制

了解 Webhook 事件未被确认时，如何查看投递尝试记录及重试逻辑。

查看事件

通过控制台的「Webhook」标签页查看特定事件详情时，你可以查看 Hipay 向该端点投递事件的次数，包括端点的最新响应、所有投递尝试记录，以及 Hipay 收到的相应 HTTP 状态码。

重试逻辑

Hipay 会对 Webhook 事件进行 6 次投递尝试，每次尝试间隔采用指数退避策略，直至收到你的服务器响应或不再重试。

重试次数	与上一次重试的间隔	与首次尝试的间隔
1	15分钟	15分钟
2	45分钟	1小时
3	2小时	3小时
4	3小时	6小时
5	6小时	12小时
6	12小时	24小时

通过邮件接收 Webhook 统计数据

你还可以每 6 小时通过邮件接收 Webhook 统计摘要（包含成功和失败的 Webhook 数量），可在「邮件接收人」设置中启用该功能。

事件处理

正确处理 Webhook 事件是确保集成业务逻辑正常运行的关键。

立即确认事件

如果你的 Webhook 脚本需要执行复杂逻辑或发起网络调用，可能会在 Hipay 确认执行完成前超时。理想情况下，你的 Webhook 处理程序代码（通过返回 2xx 状态码确认事件接收）应与该事件的其他业务逻辑分离。

处理重复事件

Webhook 端点可能会偶尔收到重复事件。建议你通过实现事件处理的幂等性来避免重复处理，例如记录已处理的事件，不再处理已记录的事件。Hipay 会在每个 Webhook 的请求头参数中提供 webhook-id 作为唯一标识，帮助你实现幂等性。了解更多幂等性相关信息。

事件顺序

Hipay 不保证事件按生成顺序投递。你的端点不应依赖事件的投递顺序，需做好相应处理。你也可以通过 API 获取任何缺失的对象。

安全性

保障端点安全对于保护客户信息至关重要。Hipay 提供多种方式，帮助你安全验证事件是否来自 Hipay。

通过 HTTPS 服务器接收事件

如果你的 Webhook 端点使用 HTTPS 地址，Hipay 会在发送 Webhook 数据前验证与服务器的连接是否安全。为此，你的服务器需正确配置 HTTPS 并配备有效的服务器证书。

验证事件来源为 Hipay

Hipay 可选择对发送至你端点的 Webhook 事件进行签名，具体方式是在每个事件的 x-callback-token 请求头中包含一个令牌。你可通过该令牌验证事件是否来自 Hipay，而非第三方。

请求头参数	说明
x-callback-token	字符串类型，你在 Hipay 的唯一 Webhook 令牌，用于验证 Webhook 来源

验证令牌前，需先从控制台的 Webhook 设置中获取你的 Webhook 令牌。每个环境都有唯一对应的令牌。