跳转到主要内容
Header

​
概覽

Twenty 中的 Webhooks 補充了 API，當 CRM 中發生某些事件時，能夠向您的應用程式發送即時通知。 Instead of continuously polling the API for changes, you can set up webhooks to have Twenty push data to your system whenever specific events occur (for example, when a new record is created or an existing record is updated). 這有助於即時且有效地將外部系統與 Twenty 保持同步。 With webhooks, Twenty will send an HTTP POST request to a URL you specify, containing details about the event. You can then handle that data in your application (e.g., to update your external database, trigger workflows, or send alerts).

​
設定 Webhook

要在 Twenty 中創建 webhook，請使用您 Twenty 應用程式中的 API 和 Webhooks 設定：
  1. 導航至設定： 在您的 Twenty 應用程式中，進入 設定 → APIs & Webhooks。
  2. 創建 Webhook： 在 Webhooks 下，點擊 + 創建 webhook。
  3. 輸入 URL： 提供在您的伺服器上希望 Twenty 發送 webhook 請求的端點 URL。 這應該是一個可以處理 POST 請求的公開訪問的 URL。
  4. 保存： 點擊 保存 來創建 webhook。 新的 webhook 將立即生效。
如果需要通過不同的端點發送不同的事件，可以創建多個 webhook。 每一個 webhook 本質上都是對所有相關事件的訂閱（目前，Twenty 將所有事件類型發送到給定的 URL；在 UI 中可能配置過濾特定事件類型）。 如果需要刪除某個 webhook，您可以從相同的設置頁面刪除它（選擇 webhook，然後選擇刪除）。

​
Events and Payloads

設置好 webhook 後，當您的 CRM 數據中發生觸發事件時，Twenty 會向您指定的 URL 發送 HTTP POST 請求。 常見的觸發 webhook 的事件包括：
  • 紀錄創建： 例如新增人員 (person.created)，創建新公司 (company.created)，創建備註 (note.created) 等。
  • 紀錄更新： 例如更新現有的人員信息 (person.updated)，編輯公司紀錄 (company.updated) 等。
  • 紀錄刪除： 例如刪除某人或公司 (person.deleted，company.deleted)。
  • 其他事件： 如適用，其他對象事件或自定義觸發器（例如，如果任務或其他對象更新，類似的事件類型會使用如 task.created，note.updated 等）。
The webhook POST request contains a JSON payload in its body. The payload will generally include at least two things: the type of event, and the data related to that event (often the record that was created/updated). 例如，新增人員的 webhook 可能會發送類似這樣的負載： 
{
  "event": "person.created",
  "data": {
    "id": "abc12345",
    "firstName": "Alice",
    "lastName": "Doe",
    "email": "alice@example.com",
    "createdAt": "2025-02-10T15:30:45Z",
    "createdBy": "user_123"
  },
  "timestamp": "2025-02-10T15:30:50Z"
}
在此範例中：
  • "event" 指定了發生了什麼（person.created）。
  • "data" 包含新紀錄的詳細信息（如果您通過 API 請求該人員，會獲得相同信息）。
  • "timestamp" 表示事件發生的時間（以 UTC 表示）。
Your endpoint should be prepared to receive such JSON data via POST. Typically, you’ll parse the JSON, look at the "event" type to understand what happened, and then use the "data" accordingly (e.g., create a new contact in your system, or update an existing one). 注意： 從您的 webhook 端點響應 2xx HTTP 狀態 以確認已成功接收很重要。 If the Twenty webhook sender does not get a 2xx response, it may consider the delivery failed. （未來的重試邏輯可能會嘗試重新發送失敗的 webhooks，因此處理完數據後儘量快速返回 200 OK）。

​
Webhook 驗証

為了確保 webhook 端點的安全性，Twenty 在 X-Twenty-Webhook-Signature 頭中包含一個簽名。 此簽名是使用您的 webhook 秘密計算的請求負載的 HMAC SHA256 雜湊。 為了驗證簽名，您需要：
  1. 將時間戳（來自 X-Twenty-Webhook-Timestamp 頭），一個冒號，和負載的 JSON 字串串連在一起。
  2. 使用您的 webhook 秘密作為密鑰計算 HMAC SHA256 雜湊
  3. 將產生的十六進位文摘與簽名頭進行比較
這是 Node.js 的範例： 
const crypto = require("crypto");
const timestamp = "1735066639761";
const payload = JSON.stringify({...});
const secret = "your-secret";
const stringToSign = `${timestamp}:${JSON.stringify(payload)}`;
const signature = crypto.createHmac("sha256", secret)
  .update(stringToSign)
  .digest("hex");