Webhook 整合

概念 2026/8/28

定義

事件驅動的跨系統資料同步模式：當來源系統發生特定事件時，自動向目標系統發送 HTTP 請求，將事件資訊寫入或觸發後續動作。

GitHub Actions 監聽 push 事件後呼叫 Notion API，是典型的 Webhook 整合模式。（github-actions-notion-commit-log）
金流服務商的付款通知（callback/webhook）使用 [[請求簽章]] 驗證真實性。（api-security-design-connection-key）
Webhook 接收端需驗證請求來源，GitHub、Stripe、LINE 等平台都用簽章機制。（api-security-design-connection-key）
一進多出的分流模式：N 個租戶共用一個對外 Webhook URL 時，接收端須自行判斷每則事件屬於哪個租戶再轉發，靠「第三方使用者識別碼 → 租戶」對照表路由。（line-login-relay-cloudflare-workers）
收件那一刻只做驗簽與入列後立刻回 200，路由與轉發丟到背景，免得卡住平台的重送機制。（line-login-relay-cloudflare-workers）
轉發時以租戶專屬金鑰重新簽章，租戶端用自己那把驗，形成「平台簽章 → 中繼站驗 → 中繼站重簽 → 租戶驗」的兩段信任鏈。（line-login-relay-cloudflare-workers）
批次合併降低下游壓力：250 毫秒或累積 20 則先到先送，把一秒幾十則壓成兩三次 POST。（line-login-relay-cloudflare-workers）
事件 ID 去重是「至少一次」投遞的補償設計，不是「恰好一次」的保證。（line-login-relay-cloudflare-workers）

Webhook 是推送模式，如果接收端暫時不可用，事件可能遺失（需重試機制）。
沒有訊息佇列的執行環境（如 Cloudflare Workers 免費方案）只能用背景任務轉發，失敗沒有內建重試保證，必須由接收端去重來容錯。（line-login-relay-cloudflare-workers）
驗簽必須用未經解析的原始 bytes，先 parse 再 stringify 會讓簽章對不上。（line-login-relay-cloudflare-workers）
接收端暴露公開 URL，需要驗證請求來源的真實性。
高併發情境下可能需要佇列（queue）來緩衝。

（無）