Webhook 通知
Webhook 是一种允许应用程序向其他应用程序发送通知的机制。 当网关为订单创建或更新交易时，会向您指定的 URL 发送通知。 通过订阅 Webhook 通知，您可确保在线商店系统实时同步最新订单信息。
Webhook 通知：
- 使用为商家配置的 Web 服务 API 协议（REST-JSON 或 NVP）。
- 包含商家配置的密钥，系统会随每次通知通过自定义标头字段 X-Notification-Secret 将该密钥发送至安全 URL。
由于无法保证及时送达，不建议将 Webhook 通知用于关键型和高响应性系统设计。 作为替代方案，您可以改用 Retrieve Transaction API。 避免在结算、对账或实时交易流等重要系统中使用 Webhook，因为它属于离线通知服务。
针对 Web 服务 API 操作的 Webhook 通知
您将收到以下 API 操作的 Webhook 通知：
- Initiate Authentication：请求返回网关为该订单推荐使用的付款人身份验证机制（例如：3DS 支付验证版本 2、3DS 支付验证版本 1、RuPay PaySecure）。
- Authenticate Payer：系统会在 Authenticate Payer 操作完成后发送此通知。 该通知仅包含身份验证操作的详细信息，不提供财务交易结果相关信息。 Authentication Payer 不支持在 JSON 有效负载中使用 order.notificationUrl，但系统会向您在 Initiate Authentication 请求中设置的 URL 发送 Webhook。
- Authorization 或 Pay：系统会在 Authorization 或 Pay 交易操作完成后发送通知。 通知中包含财务交易处理结果。
- Capture：系统会在 Capture 交易操作完成后发送通知。 通知中包含财务交易处理结果。 还支持 Standalone Capture。
- Refund：系统会在 Refund 交易操作完成后发送通知。 通知中包含财务交易处理结果。 还支持 Standalone Refund。
- Update Authorization：系统会在 Update Authorization 交易操作完成后发送通知。 通知中包含财务交易处理结果。
- Void：系统会在 Void 交易操作完成后发送通知。 通知中包含财务交易处理结果。
- Verify：系统会在 Verify 交易操作完成后发送通知。 通知中包含财务交易处理结果。
- Referral：系统会在 Referral 交易操作完成后发送通知。 通知中包含财务交易处理结果。
- Disbursement：系统会在 Referral 交易操作完成后发送通知。 通知中包含财务交易处理结果。
- Initiate Browser Payment：系统会在 IBP 交易操作完成后发送通知。 通知中包含财务交易处理结果。
- Confirm Browser Payment：系统会在 CBP 交易操作完成后发送通知。 通知中包含财务交易处理结果。
在 Merchant Administration 中配置 Webhook 通知
要配置 Webhook 通知：
- 请登录 Merchant Administration 门户，进入管理 > Webhook 通知。
- 请配置以下 Webhook 通知参数：
- 通知 URL：配置全局通知 URL，以接收所有交易的更新。 您提供的 URL 必须符合 IETF 标准。 否则，系统将拒绝该请求。
如果需要为特定交易覆盖此全局 URL，请在交易请求的 order.notificationUrl 字段中指定该 URL。 后续交易的通知将发送至交易中指定的 URL（如提供）或订单上一次使用的 URL。
根据新版 IETF 标准，username:password@host.com 格式已不再适用。 如果使用此格式，Webhook 仍会发送，但用户名和密码将被忽略。 使用通知密钥进行身份验证。
- API 格式：Mastercard Gateway 会按照您在 Merchant Administration 中配置的格式（REST-JSON 或 NVP）发送 Webhook 通知。 系统将使用提交交易请求时的版本来发送通知。
- 检查通知密钥：通知密钥是由网关生成的 32 位随机字符串。 配置 Webhook 通知时，可以在 Merchant Administration 门户查看该密钥。 对于安全 (https://) URL，网关会在消息的
X-Notification-Secret标头中包含该密钥。
- 通知 URL：配置全局通知 URL，以接收所有交易的更新。 您提供的 URL 必须符合 IETF 标准。 否则，系统将拒绝该请求。
Webhook 通知成功送达
如果您的系统在 2 秒内返回包含 HTTP 200 状态码的成功确认消息，网关即视为 Webhook 通知已成功送达。
网关不要求客户提供任何特定的标头，但目标 URL 返回的响应标头大小不得超过 32KB。 系统会持续重试发送 Webhook 通知，直至收到响应。
Mastercard Gateway 强制要求商家仅通过安全 (HTTPS://) 端点接收 Webhook 通知，以保障安全与合规
Webhook 通知流程与重发
- 发送尝试：事件发生后，网关会在 3 天内最多向商家尝试发送 20 次 Webhook 通知。
- 重试间隔：网关将按以下间隔重试：10 秒、30 秒、2 分钟、5 分钟、30 分钟、4 小时（重复 4 次）、8 小时、12 小时（重复 4 次）。
- 超时处理：网关等待 30 秒后，将记录 Webhook 通知的超时异常。
- 成功送达：如果您的系统在 3 天内返回 HTTP 200 状态码，网关即视为 Webhook 通知已成功送达。
- 停止尝试：3 天内累计尝试发送 Webhook 通知满 20 次后，将停止重试。
重发通知管理
您可以在 Webhook 通知中使用以下字段来管理重发通知：
- X-Notification-ID：该标头用于唯一标识每个通知，重复交易的标识值保持一致。
- X-Notification-Attempt：该标头表示已尝试发送通知的次数。