無需管道工程，偵錯 Webhook
最後更新:
每一個 Webhook 整合都始於同一個不起眼的問題：服務商的伺服器需要呼叫你的程式碼，而你的程式碼執行在你的筆記型電腦上，外界無法存取你的筆記型電腦。所以在你偵錯真正的工作——簽名驗證、負載形狀、處理器邏輯——之前，你得先搭建管道工程：一條隧道、一次預發布部署、一個轉發到你機器的公共 URL。本文講的是如何用臨時接收器跳過這一步，比如本站的 Webhook 測試器：建立一個位址，把服務商指向它，觸發事件，然後讀取確切到達的內容。然後按照真相而不是文件來撰寫你的處理器。
偵錯循環，以及它在哪裡斷裂
健康的 Webhook 循環很短：服務商中發生一個事件，服務商把簽名的負載 POST 到你的端點，你的端點驗證簽名、解析請求內文、完成工作並回覆 200。不健康的循環——人人都熟悉的那種——在每一步周圍都加了一層迷霧。服務商的儀表板說投遞失敗了，回傳 500，或 404，或什麼都沒說。那是你的程式碼在應答、中間的代理，還是端點 URL 打錯了字？重試帶著同一個事件 id 到達——還是說它是同一筆付款的一個新事件？文件展示了一個整潔的 JSON 範例，但生產負載帶有額外的欄位、範例壓平的嵌套物件，偶爾還有範例從未提及的內容類型。Stripe 和 GitHub 的 Webhook 文件（連結在下方）都強調同樣的紀律——驗證簽名、快速應答、處理重複——而在你能看到一次真實投遞之前，這些都無從練起。
斷裂幾乎從來不在有趣的邏輯裡。它在你以為傳送了什麼與實際傳送了什麼之間的鴻溝裡：在你的框架已經解析並重新序列化的請求內文上計算出的簽名標頭、從錯誤的儀表板複製的金鑰、你的 switch 語句拼寫略有不同的事件類型、一個對儀表板裡的測試事件有效卻對生產環境的真實事件無效的處理器。所有這些從你自己的日誌內部都看不見，因為你的日誌始於你的程式碼已經做出第一個錯誤假設之後。由不是你的程式碼的東西記錄的一次被擷取的投遞，是能讓循環縮短的事實真相。
臨時接收器能為你買到什麼
臨時接收器是一個公共 URL，它的全部工作就是接受一切並展示給你：本站的 Webhook 測試器 一鍵建立它，保留 30 分鐘，記錄最多 50 次投遞及其方法、路徑與查詢參數、標頭和請求內文（每個最多 256 KB），然後自動刪除一切。它買到的是順序。你不必為了觀察流量就把寫了一半的處理器部署到公共機器上——然後同時偵錯部署和處理器——而是把觀察與實作分開。先看幾個真實事件到達，學習它們實際的形狀。然後在本機對照被擷取的負載撰寫處理器，你可以手動把它們重播到自己的測試中。最後把服務商指向真實端點，再觸發一次事件，此時你已經確切知道一次正確的投遞長什麼樣，以及你的處理器應該對它做什麼。
當對話跨越團隊邊界時，它還能買到證據。「你的 Webhook 把金額傳成了字串」是一場爭論；一條顯示 "amount": "2000" 的被擷取投遞是一個事實。同一條擷取能回答服務商支援工單會問的問題——哪個事件 id、哪個時間戳記、哪個簽名標頭在場——而無需一輪日誌考古，它也能判定一次缺失的投遞到底是根本沒傳送，還是傳送到了某個被遺忘的舊測試位址。同樣的哲學，相鄰的工具：當問題是重新導向而非負載時，HTTP 狀態鏈追蹤器 從伺服器的視角展示一個 URL 的行為。
工作流程：配合本工具
一：開啟 Webhook 測試器 並建立一個鉤子。複製接收 URL——從這一刻起把這個 URL 當作憑證，原因見下一節。二：把它貼到服務商的 Webhook 設定中作為測試端點——Stripe、GitHub 和大多數服務商都允許幾個端點，所以你的生產端點不受影響——或者如果你偵錯的是自己控制的傳送方，就貼到你自己的服務配置裡。三：以誠實的方式觸發事件。使用服務商的真實流程（測試模式付款、向草稿分支的真實推送），而不僅僅是儀表板的「傳送測試事件」按鈕，因為測試事件有時恰恰在你在乎的欄位上與真實事件不同。四：讀取擷取。先檢查方法和內容類型，再檢查簽名和事件標頭，然後在信任任何美化列印檢視之前先看原始文字的請求內文。
五：對照這條擷取撰寫或修復你的處理器。對照原樣收到的原始請求內文驗證簽名——這正是擷取展示未解析位元組的原因——並讓你的處理器對你現在能看到在重試間穩定的事件 id 做到冪等。六：刪除鉤子（或讓它的 30 分鐘到期），從服務商那裡移除測試端點，把投遞重新指向你的真實處理器。七：再觸發一次事件，看著你自己的端點應答它。如果現在它失敗了，被擷取的良好投遞與你的處理器的行為之間的差異就是全部的 bug，而這個差異是可以檢查而不是猜測的。
安全：URL 就是憑證
一個任何人都能讀的接收器不需要登入，這種便利有你應該留意的代價：URL 中的鉤子 id 是唯一的憑證，它同時授權傳送和查看。任何獲得 URL 的人——從截圖、聊天記錄、共享螢幕——都能讀取鉤子存活期間擷取的每一個負載。所以規則就是密碼規則：不要公開張貼 URL，不要把它用於即時生產饋送，工作階段結束時刪除鉤子，而不是讓擷取內容坐滿那半小時。負載從另一面也值得同樣的尊重：一次真實的付款或推送負載可能包含客戶電子郵件位址、訂單詳情和你不會貼到公開 gist 裡的中繼資料，而一條被擷取的投遞正是這種文件。測試模式、草稿倉庫和合成事件的存在，正是為了讓偵錯產物裡沒有任何值得竊取的東西。
測試器自身的限制是安全故事的一部分，並已在工具頁上明確說明：擷取內容只在檢查伺服器上保存到鉤子過期或你刪除它為止——最長 30 分鐘——請求內文上限為 256 KB，鉤子上限為 50 個請求，接收器從不擷取、跟隨或重播任何內容，因此被擷取的負載無法變成伺服器的出站流量。判斷仍然留給你。如果一個負載落到陌生人手裡會成為問題，它根本不屬於共享查看器：那次偵錯工作階段請用你自己的基礎設施，就像對待生產金鑰一樣。便利工具的位置，是在構成大多數偵錯日常的低敏感度工作上掙來的。
局限：只接收，只檢查
本工具刻意不做的是檢查之後的一切。它不把投遞轉發到你的筆記型電腦（那是隧道的工作，而當處理器已經存在、你要即時迭代時，隧道正是合適的工具），它不把被擷取的請求重播到你的真實端點，它不轉換或簽名任何內容，它也不保留超過 30 分鐘的歷史。這些缺失正是設計本身：會轉發的接收器是一個讓你的流量流經它的代理，會重播的接收器是一個傳送方，兩者都是比一個 30 分鐘收件匣更大的信任。把測試器用在它適合的階段——在建置處理器之前和建置過程中看清真相——而一旦整合上線，就讓位於你自己的端點，在你自己的驗證和日誌之後接管。