跳至主要內容

Webhook

Logto Webhook 提供各種事件的即時通知，包括使用者帳號、角色、權限、組織、組織角色、組織權限，以及 使用者互動 的變更。

當事件被觸發時，Logto 會向你提供的 Endpoint URL 發送 HTTP 請求，內容包含事件的詳細資訊，例如使用者 ID、使用者名稱、電子郵件及其他相關細節（關於 payload 與 header 所包含的資料，請參閱 Webhook 請求）。你的應用程式可以處理這個請求並執行自訂動作，例如發送電子郵件或更新資料庫資料。

我們會根據用戶需求持續新增更多事件。如果你有特定業務需求，歡迎告訴我們。

為什麼要使用 Webhook？​

Webhook 提供應用程式間的即時通訊，免除輪詢需求，實現資料的即時更新。它們簡化了應用程式整合與工作流程自動化，無需複雜程式碼或專有 API。

以下是 CIAM 常見 Webhook 使用案例：

  • 發送電子郵件： 設定 Webhook，讓新使用者註冊時自動發送歡迎信，或在使用者從新裝置或地點登入時通知管理員。
  • 發送通知： 設定 Webhook，當使用者註冊時觸發 CRM 系統的虛擬助理，提供即時客戶支援。
  • 執行額外 API 呼叫： 設定 Webhook，根據使用者的電子郵件網域或 IP 位址驗證其存取權，然後使用 Logto Management API 指派具備資源權限的適當角色。
  • 資料同步： 設定 Webhook，讓應用程式即時獲知如使用者帳號停用或刪除等變更。
  • 產生報表： 設定 Webhook 接收使用者登入活動資料，並用於產生使用者參與度或使用模式報表。

術語​

項目說明
Event（事件）當特定動作發生時，會觸發具有特定類型的 hook 事件。例如，當使用者完成註冊流程並建立新帳號時，Logto 會發出 PostRegister hook 事件。
Hook（鉤子）連接到特定事件的一個或一系列動作。動作可以是呼叫 API、執行程式碼片段等。
Webhookhook 的一種子類型，表示以事件 payload 呼叫 API。
假設開發者希望在使用者透過新裝置登入時發送通知，可以新增一個 webhook，將 PostSignIn 事件呼叫其安全服務 API。

以下是在 Logto 中為 PostSignIn 事件啟用兩個 webhook 的範例：

常見問題​

Logto 支援同步 webhook 嗎？​

雖然同步 webhook 能讓使用者登入流程更順暢，但目前尚未支援（未來會支援）。因此，目前所有依賴同步 webhook 的情境都需要不同的替代方案。如有疑問，歡迎聯繫我們。

如何處理使用者權限變更？​

請參閱 管理使用者權限變更 指南。

如何偵錯 webhook 超時？​

接收 Webhook 的 endpoint 應盡快回傳 2xx 回應，告知 Logto Webhook 已成功接收。由於不同用戶對 Webhook 的處理邏輯差異極大，過於複雜的任務可能需數秒，導致 Logto Webhook 超時。最佳做法是維護自己的事件佇列；收到 Logto Webhook 時，將事件寫入佇列並立即回傳 2xx 給 Logto，然後讓自己的 worker 逐步處理佇列任務。若 worker 發生錯誤，請於自己的伺服器處理。

可以從 PostSignIn webhook 取得 client IP 嗎？​

可以，你可以在 Webhook payload 中取得 IP 位址、user agent 等資訊。如果需要目前未支援的資訊，歡迎在 GitHub issues 提出功能需求，或聯繫我們。

Webhooks vs. polling