什么是 Webhook？面向在线商家的通俗解释

如果您在线收款，迟早会有人向您要一个 webhook URL。听起来很技术，其实原理很简单。

一句话解释 webhook

Webhook 是一个系统在某件事发生的那一刻，自动发送给另一个系统的消息。

可以把它想象成快递通知。您不会每五分钟给快递员打电话问"包裹到了吗？"，而是包裹到达时快递员给您发消息。Webhook 在软件之间做的就是同样的事。

轮询与 webhook

没有 webhook，您的网站就得不停地问支付网关："订单 1042 付款了吗？现在呢？现在呢？"这叫做轮询。它慢、浪费资源，顾客也要等更久。

有了 webhook，您的网站只需等待。付款确认后，网关会主动通知您的网站："订单 1042 已付款。"

Webhook 长什么样

从技术上讲，webhook 是发往您服务器某个地址的 HTTPS POST 请求，例如 https://yourshop.com/webhooks/paywise。请求内容是一段简短的 JSON：

{
  "event": "payment.paid",
  "data": {
    "reference": "TRX-...",
    "merchant_reference": "INV-1042",
    "payment_method": "QRIS",
    "amount": "...",
    "currency": "IDR",
    "status": "paid"
  }
}

您的网站读取消息，找到订单 INV-1042，将其标记为已付款，然后就可以立即发货或开通服务。

为什么支付依赖 webhook

• 订单即时更新。 钱一到账订单就变为已付款，即使在凌晨 3 点。
• 无需人工核对。 不需要有人对照银行流水和订单。
• 顾客离开也不影响。 即使顾客付款后关闭了浏览器，您的网站仍会收到通知。
• 减少伪造凭证。 确认付款的是网关，而不是截图。请阅读如何防止伪造转账凭证。

如何安全地处理 webhook

1. 验证签名。 任何人都可以向您的 URL 发送 POST 请求。PAYWISE 会用您的密钥为每个 webhook 签名，放在 X-PAYWISE-Signature 请求头中（原始请求体的 HMAC-SHA256）。不匹配的一律拒绝。详细步骤：验证 PAYWISE webhook 签名。
2. 快速响应。 保存消息后立即返回 2xx 状态码，耗时的工作（发邮件、更新库存）之后再做。
3. 做好重复接收的准备。 投递失败时会重新发送，同一事件可能收到不止一次。订单只标记一次已付款。
4. 使用 HTTPS。 不要在普通 http:// 地址上接收付款通知。
5. 不要只相信跳转页。 顾客付款后返回的页面可能被跳过或伪造，webhook 才是真正的确认。

PAYWISE 中的 webhook

• 在 Webhook 页面设置 URL 和订阅的事件，并用测试按钮检查您的服务器是否正常响应。
• PAYWISE 发送的事件包括 payment.paid、payment.expired 和 payment.failed。
• 如果您的服务器没有响应，PAYWISE 会自动重试：大约在 1 分钟、5 分钟、30 分钟和 2 小时后。
• 每次尝试都记录在交易中，服务器修复后您也可以手动重新发送 webhook。

不确定 webhook 是否送达？API 日志指南告诉您在哪里查看。完整说明请参阅开发者文档。