跳轉到主要內容

如何在本地測試 Webhook:用隧道在 localhost 接收支付回調

如何在本地測試 Webhook:為什麼 localhost 收不到回調、如何用隧道暴露本地服務,以及如何發送測試回調、模擬支付結果和重新投遞。

發佈於 約 4 分鐘閲讀

手繪插畫:一條 Webhook 從雲端穿過隧道,到達一台顯示 localhost:3000 的筆記本電腦,旁邊一個人正指着它
本文目錄
  1. 為什麼 localhost 收不到 Webhook
  2. 第一步:用隧道暴露本地服務
  3. 第二步:登記隧道地址
  4. 第三步:向本地服務發送 Webhook
  5. 第四步:重投、重試與補回
  6. 本地測試 Webhook 容易踩的坑
  7. 總結

要在本地測試 Webhook,你需要一個能轉發到你本機服務的公網 HTTPS 地址,因為支付平台訪問不到 localhost。cloudflared 或 ngrok 這類隧道工具,一條命令就能給你這樣一個地址;把它登記為回調地址,發來的事件就會到達你本地的代碼,你可以在那裏打斷點、看日誌、邊改邊試。

這篇文章説明如何對着 KukoPay 沙箱在本地測試 Webhook:建立隧道、登記地址、向它發送測試回調和模擬支付結果、重新投遞,以及本地環境裏容易踩的坑。

為什麼 localhost 收不到 Webhook

Webhook 是從平台的服務器發往你的服務器的請求。localhost 和內網地址(192.168.x.x、10.x.x.x)只在你自己的電腦或網絡裏才有意義,平台根本訪問不到。KukoPay 會直接拒絕它們:notify_url 和 Webhook 端點在沙箱裏也必須是公網 HTTPS 地址,填 localhost 或內網地址會返回 400。

return_url 不一樣:它是買家瀏覽器付款後跳轉的地方,所以在沙箱裏可以指向 http://localhost:3000/...。需要隧道的只有 Webhook。

第一步:用隧道暴露本地服務

先在本地啓動 Webhook 接收端(例如 3000 端口),再打開一條通往它的隧道:

cloudflared tunnel --url http://localhost:3000
# 或者
ngrok http 3000

兩者都會打印出一個公網 HTTPS 地址,例如 https://random-words.trycloudflare.com,轉發到你的端口。你的回調地址就是這個地址加上路由:https://random-words.trycloudflare.com/webhooks/kukopay。

第二步:登記隧道地址

按你的接入接收事件的方式,有兩種做法:

  • 按訂單: 創建沙箱訂單時把隧道地址作為 notify_url 傳入。這類回調用應用的回調簽名密鑰簽名,在 開發者 → API 密鑰 頁面簽發。
  • 作為端點: 在 開發者 → Webhook 用隧道地址創建一個沙箱 Webhook 端點,並複製它的簽名密鑰(只顯示一次)。見 如何管理多個 Webhook 端點。

請使用沙箱(kuko_test_)密鑰和沙箱簽名密鑰:正式環境的密鑰永遠驗不過沙箱的 Webhook。

第三步:向本地服務發送 Webhook

不需要真的付款,就能產生 Webhook:

  • 在 開發者 → 沙箱聯調 中發送測試回調:選擇目標和事件類型,頁面會顯示發出的請求和你本地服務的返回。它的構造和簽名與真實回調完全相同,帶 "test": true,id 以 evt_test_ 開頭,不會被記錄為事件。
  • 對一筆還沒打開過收銀台的沙箱訂單模擬支付結果:成功、失敗或過期都會走真實流程,所以你會收到真正的 payment.succeeded(或 payment.failed / payment.expired),並按正常規則重試。模擬成功的訂單之後還可以退款,用來測試退款回調。
  • 用 4242 4242 4242 4242 等測試卡在沙箱收銀台付款,走完整的買家流程,見 支付測試卡號大全。

第四步:重投、重試與補回

本地開發意味着你的服務有時會掛、會重啓、會出錯——這正好用來測試失敗路徑:

  • 重試。 10 秒內沒有收到 2xx 的投遞,會在 30 秒、2 分鐘、10 分鐘、30 分鐘和 2 小時後重試。故意返回 500,看同一個事件 id 再次到達。
  • 手動重投。 每次投遞及其狀態都列在 開發者 → Webhook 裏,修好處理代碼後可以再發一次。
  • 補回。 如果你的筆記本休眠期間重試已經用完,用事件接口把漏掉的讀回來,見 收不到 Webhook 怎麼辦。

本地測試 Webhook 容易踩的坑

  • 隧道地址會變。 免費隧道重啓後地址通常會變。請更新端點的地址:還在排隊的重試和手動重投都會發到端點的當前地址。按訂單傳入的 notify_url 跟隨訂單不變,所以重啓隧道後請創建新訂單。
  • 不能重定向。 3xx 算投遞失敗。回調地址要指向確切的路由,不要指向會跳轉的頁面。
  • 對原始請求體驗簽。 開發服務器和中間件很喜歡幫你解析 JSON;請對原始字節驗簽,再解析,見 Webhook 驗簽怎麼做。
  • 不要為測試回調履約。 檢查 "test": true,確認收到但不做任何處理。
  • 處理重複投遞。 把事件 id 寫入帶唯一約束的表,重試的事件只處理一次,見 支付回調冪等處理。

總結

  • 在本地測試 Webhook,要用隧道(cloudflared、ngrok)暴露本地服務並登記公網 HTTPS 地址——即使在沙箱裏,localhost 也會被拒絕;
  • 把它登記為沙箱 notify_url 或沙箱 Webhook 端點,並使用對應的沙箱密鑰;
  • 用測試回調、模擬支付結果或測試卡付款來產生事件;
  • 用重試、手動重投和事件接口測試本地服務掛掉時會發生什麼;
  • 隧道地址變了就更新端點,避免重定向,對原始請求體驗簽,並按事件 id 去重。

在沙箱裏把它跑通

註冊商戶後即可申請測試密鑰,不需要等待資質審核。