Webhook
Logto Webhook 提供各種事件的即時通知，包括使用者帳號、角色 (Role)、權限 (Permission)、組織 (Organization)、組織角色 (Organization Role)、組織權限 (Organization Permission) 以及 使用者互動 的變更。
當事件被觸發時，Logto 會非同步地向你提供的 endpoint URL 發送 HTTP 請求。該請求包含事件的詳細資訊，例如使用者、應用程式與請求上下文。請參閱 Webhook 請求 以取得 payload 與 header 參考。
Webhook 傳遞發生在驗證請求 (Authentication request) 之外，無法改變當前流程的結果。若需在登入繼續前必須完成的同步程式碼，請使用 Actions。
我們會根據用戶需求持續新增更多事件。如果你有特定業務需求，歡迎聯絡我們。
為什麼要用 Webhook？
Webhook 提供應用程式間的即時通訊，省去輪詢需求，實現即時資料更新。它們簡化應用程式整合與工作流程自動化，無需複雜程式碼或專有 API。
以下是 CIAM 常見 Webhook 使用案例：
- 發送電子郵件：設定 Webhook，讓新使用者註冊時自動發送歡迎信，或在使用者從新裝置 / 地點登入時通知管理員。
- 發送通知：設定 Webhook，當使用者註冊時觸發 CRM 系統的虛擬助理，提供即時客戶支援。
- 執行額外 API 呼叫：設定 Webhook，透過檢查使用者的電子郵件網域或 IP 位址來驗證存取，然後使用 Logto Management API 指派具備資源權限的適當角色 (Role)。
- 資料同步：設定 Webhook，讓應用程式即時獲知如使用者帳號停用或刪除等變更。
- 產生報表：設定 Webhook 接收使用者登入活動資料，並用於產生使用者參與度或使用模式報表。
術語
| 項目 | 說明 |
|---|---|
| Webhook 事件 | Logto 可傳遞的支援事件類型，例如 PostSignIn 或 User.Created。 |
| Webhook | 訂閱一個或多個事件並將其 payload 發送到 HTTP endpoint 的設定。 |
例如，若要在使用者登入後通知安全服務，可建立訂閱 PostSignIn 的 Webhook。
以下是在 Logto 為 PostSignIn 事件啟用兩個 Webhook 的範例：
常見問題
Webhook 可以做同步驗證決策嗎？
不行。Webhook 屬於非同步通知，因此其回應無法允許、阻擋或修改當前驗證流程。
當 Logto 需要在登入繼續前執行自訂程式碼、呼叫外部 API 或更新使用者時，請使用 Actions。由於 Actions 為同步執行，請確保其外部依賴快速且穩定。
如何除錯 webhook 超時？
Webhook 接收端應盡快回傳 2xx 回應，告知 Logto Webhook 已成功接收。由於不同用戶對 Webhook 的處理邏輯差異極大，過於複雜的任務可能需數秒，導致 Logto Webhook 超時。最佳實踐是維護自己的事件佇列：收到 Logto Webhook 時，將事件寫入佇列並立即回傳 2xx 給 Logto，然後讓自己的 worker 逐步處理佇列任務。若 worker 發生錯誤，請在自己的伺服器上處理。
可以從 PostSignIn webhook 取得 client IP 嗎？
PostSignIn webhook 取得 client IP 嗎？可以，你可以在 Webhook payload 中取得 IP 位址、user agent 等資訊。若你需要目前尚未支援的資訊，歡迎在 GitHub issues 建立功能需求，或聯絡我們。