如何在本地測試 Webhook:用隧道在 localhost 接收支付回調
如何在本地測試 Webhook:為什麼 localhost 收不到回調、如何用隧道暴露本地服務,以及如何發送測試回調、模擬支付結果和重新投遞。
本文目錄
要在本地測試 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去重。
在沙箱裏把它跑通
註冊商戶後即可申請測試密鑰,不需要等待資質審核。