- 集成指南
- 支持的功能（其他功能）
- Webhook 通知
Webhook 通知
订阅 Webhook 通知后，在网关中创建或更新订单交易时您可以在系统中收到通知。 这样您可以相应地更新商店系统。 Webhook 通知包含 Retrieve Transaction 操作的响应。
Webhook 通知对于关键的响应系统设计不是理想选择，因为无法保证通知的送达时间，因此商家发起的 Retrieve Transaction API 是备选方案。 不建议在结算和对帐或实时交易流等重要系统中使用 Webhook，因为它是一种离线通知服务。
与 Hosted Checkout 集成的 Webhook 通知
对于 Hosted Checkout 集成，如果您使用身份验证 API 进行 3DS 支付验证，将收到两条 Webhook 通知，使用 3DS1 功能则会收到一条。
- 一条是在付款人身份验证完成后
- 一条是在 Authorization/Pay 交易完成后
付款人身份验证 Webhook 会仅包含身份验证操作的详细信息。 不会包含有关财务交易结果的信息。 Authorization/Pay Webhook 会包含财务交易处理的结果。
配置 Webhook 通知
您可以在 Merchant Administration 中配置 Webhook 通知的以下参数：
- 通知 URL—您可以在 Merchant Administration 中配置全球通知 URL 来在此 URL 接收所有交易更新通知。 如果您希望覆盖每个交易的全球 URL，请在交易请求的
order.notificationUrl字段中提供 URL。 对于后续交易，通知发送到交易中提供的 URL（如果提供）或上一次订单使用的 URL。 - API 格式—American Express Payment Gateway 使用您在 Merchant Administration 中配置的格式（REST 或 NVP）发送 Webhook 通知。
您提供的 URL 必须符合 URL IETF 标准（参见 http://www.ietf.org/rfc/rfc2396.txt），否则请求将被拒。
通知在用于提交交易请求的版本中发送。
确保 Webhook 通知的完整性
如果您出于某些业务关键原因需要利用 Webhook 通知内容，您应考虑采取以下步骤来确保通知收到的数据的完整性。
- 作为端点提供安全 (https://) URL，并
- 检查通知密码
通知密码是网关生成的 32 个字符的随机字符串。 在配置 Webhook 通知时密码将显示在 Merchant Administration 中。 仅对于安全 (https://) URL，网关会在消息的 X-Notification-Secret 标头中包含密码。
网关执行验证以确保您只能提供安全的 (https://) 通知 URL 作为端点。
或者，您可以使用收到的通知中的识别码来执行 Retrieve Transaction 操作以获取更改的详细信息。
接受 Webhook 通知
如果您的系统在 2 秒内以包含 HTTP 200 状态代码的成功确认消息作出响应，网关将认为 Webhook 通知已成功传送。
网关会尝试以发生的交易更新的相同顺序发送通知，除非通知需要重新发送。 当初始通知未成功提交或未成功收到确认消息时将发生重新提交。 在这种情况下，网关会在事件发生后 3 天内尝试重新发送通知，最多尝试 20 次。 这可能导致向您的系统发送重复通知。 您可以在 Webhook 通知中使用以下字段来处理重新提交的通知：
- X-Notification-Id 标题唯一识别通知。 重复交易的标题相同。
- X-Notification-Attempt 标题指示尝试发送通知的次数。
您可以重新使用前端集成的代码来接受 Webhook 通知。