什麼是 Webhook？應用程式點樣互相通知

Webhook 係一個自動訊息，喺某件事情發生嗰一刻，由一個服務發送畀你嘅應用程式。當客戶嘅付款成功，Stripe 會發一個 webhook 去你應用程式入面嘅一個地址，講明「付款成功，以下係詳情」，然後你嘅應用程式就會作出反應——標記訂單已付款、發收據、解鎖帳戶。簡單嚟講：API 係你嘅應用程式問另一個服務一個問題；webhook 就係另一個服務呼叫你嘅應用程式，話畀你知一件事。

用 AI 建造嘢時點解重要

一旦你嘅應用程式開始收款、接收其他工具提交嘅表格，或者連接 GitHub、Shopify 或者日曆等服務，你就會遇到 webhook。佢哋通常係知道某件事發生嘅正確方法——但亦係 AI 建造嘅應用程式最容易出現微妙錯誤嘅地方：

• 個端點接受任何請求，所以任何人都可以偽造一個「付款成功」事件。
• 應用程式喺結賬完成後跳轉嘅頁面上就授予存取權，而唔係喺 webhook 度授予。咁樣，如果有人太早關咗個分頁，就會付咗錢但冇得用；而如果有人搵到成功頁面嘅網址，就可以免費用。
• 同一個事件到咗兩次，客戶就收到兩張訂單或者兩封電郵。

明白 webhook 點運作，你就可以事先要求必要嘅保護。

日常比喻：送貨短訊

你可以用兩種方法知道包裹有冇到。你可以每十分鐘行到前門睇吓（呢個叫 polling——你嘅應用程式不斷呼叫 API 問「有冇新嘢？」）。或者送貨員可以喺送到之後發短訊畀你（呢個就係 webhook）。

短訊明顯比較好——前提係你信得過佢。如果任何人都可以發「包裹已送到」嘅短訊畀你，你會想有方法確認佢真係來自送貨員。而如果短訊嗰陣你部電話關咗機，你會希望送貨員之後再試一次。呢兩個問題——核實同重試——正正係令 webhook 變得棘手嘅大部分原因。

Webhook 逐步點運作

1. 你喺應用程式嘅後端建立一個端點：一個好似 https://yourapp.com/webhooks/stripe 嘅網址，接受 POST 請求。
2. 你將呢個網址登記去服務商，並揀選你想要嘅事件（例如「結賬完成」同「訂閱取消」）。
3. 服務商會俾你一個簽名 secret。 你要將佢儲存為伺服器上嘅 secret——見環境變數同 secrets。
4. 事件發生。 服務商向你嘅網址發送一個 HTTP 請求，內容係描述事件嘅 JSON，同埋一個簽名標頭。
5. 你嘅應用程式核實簽名，記錄事件 ID，快速回覆成功代碼（200），然後先執行工作。
6. 如果你嘅應用程式冇回覆成功，好多服務商之後都會再試。

簽名

簽名證明請求係來自服務商，並且冇被更改。例如 Stripe 會用簽名 secret，對請求主體同時間戳計算一個 HMAC（一種有鑰匙嘅指紋，用 SHA-256），然後放喺 Stripe-Signature 標頭入面發送。你嘅應用程式用自己那份 secret 做同樣嘅計算；如果結果一樣，就證明請求係真嘅。由於時間戳亦有簽名，你可以拒絕有人錄低咗、之後重播嘅舊請求——根據 Stripe 截至 2026 年 9 月嘅文件，佢哋嘅函式庫預設容許五分鐘嘅誤差。

有個實際細節：簽名係基於原始請求主體計算。如果你嘅框架喺核實之前已經解析並重新格式化咗 JSON，核實就會失敗。呢個係非常常見嘅錯誤。

重試、重複同次序

各個服務商都唔同，所以要查閱每個服務商嘅文件。截至 2026 年 9 月：

Stripe 嘅文件亦講明，事件唔保證會按發生嘅次序抵達，而且同一個事件偶爾都可能到咗多於一次，所以建議你記錄事件 ID。

呢個一般性嘅道理適用於任何服務商：事件可能會遲到、重複到達，同埋次序錯亂。你嘅處理程式應該係冪等嘅——即係同一個事件處理兩次，效果同只處理一次一樣。

實例：解鎖付費課程

你賣一個網上課程。學生㩒咗購買，喺 Stripe 嘅代管結賬頁面付款，然後被送返你嘅網站。

脆弱嘅做法：「多謝」頁面負責解鎖課程。如果學生喺跳轉途中關咗瀏覽器，佢已經付咗錢但冇得用。如果有人估到多謝頁面嘅網址，佢就可以唔付錢都有存取權。

用 webhook 嘅做法：

1. 當 Stripe 確認付款，佢會發送一個 checkout.session.completed 事件去 /webhooks/stripe。
2. 你嘅後端用簽名 secret 核實簽名。如果失敗，就回覆 400，並且唔做任何嘢。
3. 檢查呢個事件 ID 之前有冇被處理過。如果有，就回覆 200，然後停止。
4. 儲存事件 ID，回覆 200，然後先授予學生存取權，並發送歡迎電郵。
5. 「多謝」頁面只係話「已收到付款——你嘅課程好快就會出現」，並檢查學生嘅存取狀態。

之後，如果訂閱被取消或者信用卡扣款失敗，其他 webhook 事件會話畀你嘅應用程式移除或者暫停存取權。咁樣訂閱產品就可以同帳單保持同步——見什麼是 SaaS同點樣為你嘅應用程式加入付款功能。

重要術語

• Endpoint（端點）： 你應用程式入面接收 webhook 嘅網址。
• Event / payload（事件／內容）： 發生咗咩事，以及描述佢嘅數據（通常係 JSON）。
• Signing secret（簽名 secret）： 用嚟核實簽名嘅共享 secret。
• Idempotent（冪等）： 用同一個輸入執行多次，結果都一樣，無問題。
• Polling（輪詢）： 不斷向 API 查詢有冇改動，而唔係等待 webhook。
• Tunnel（通道）： 一個工具，喺開發期間為你部電腦提供臨時公開網址，等 webhook 可以到達。

常見錯誤同誤解

• 唔核實簽名。 端點網址並唔係 secret。核實先係令請求值得信任嘅原因。
• 回覆之前先做慢工作。 喺回覆之前發送電郵或者生成 PDF，可能會超時，超時就會觸發重試，重試就會造成重複。
• 假設一次性、按次序到達。 記錄事件 ID，唔好依賴到達次序。
• 用預覽網址。 Webhook 需要穩定、公開嘅地址。私人預覽同 localhost 互聯網都夠唔到；用你已發布嘅網址（或者測試時用通道）。
• 混用測試同正式 secret。 服務商通常會為測試模式同 live 模式發出唔同嘅簽名 secret。兩個都要儲存，並且用啱嘅一個。
• 對重要決定盲目相信 payload。 對於高風險嘅動作，收到事件之後，由服務商嘅 API 攞最新狀態去核對，係合理嘅做法。

要求你嘅 AI 建造工具做咩

喺伺服器上加一個 POST /webhooks/stripe 端點。用原始請求主體同 STRIPE_WEBHOOK_SECRET 呢個 secret 核實 Stripe 簽名。簽名唔啱就用 400 拒絕。儲存每個事件 ID，並跳過已處理過嘅事件。快速用 200 回覆，然後處理 checkout.session.completed：將訂單標記為已付款，並發送收據。記錄事件類型。唔好喺結賬成功頁面上授予存取權。

之後測試佢：從服務商嘅 dashboard 發送一個測試事件，再發一次同一個事件，然後再發一個簽名錯誤嘅請求。只有第一個應該改變任何嘢。

Mythex 嘅 Webhook

Mythex 冇一個獨立嘅 webhook 服務；你要求 agent 喺你應用程式自己嘅後端加一個 webhook 端點，然後將服務商指向你已發布嘅網址，因為 webhook 需要公開地址。簽名 secret 放入你項目嘅 secrets，如果你改動咗一個即時應用程式嘅 secret，就要重新發布。處理 webhook 嘅 docs 食譜有一段起始提示，而商店範本對於需要收款嘅應用程式係一個好起點。

常見問題