e02c24bd3a
Created by Github action --------- Co-authored-by: Abdul Rahman <ar5438376@gmail.com> Co-authored-by: Crowdin Bot <support+bot@crowdin.com> Co-authored-by: github-actions <github-actions@twenty.com> Co-authored-by: Charles Bochet <charles@twenty.com>
87 lines
5.3 KiB
Plaintext
87 lines
5.3 KiB
Plaintext
---
|
||
title: Webhooks
|
||
image: /images/docs/getting-started/webhooks.png
|
||
info: 了解如何使用我們的 Webhooks。
|
||
---
|
||
|
||
<Frame>
|
||
<img src="/images/docs/getting-started/webhooks.png" alt="Header" />
|
||
</Frame>
|
||
|
||
## 概覽
|
||
|
||
Twenty 中的 Webhooks 補充了 API，當 CRM 中發生某些事件時，能夠向您的應用程式發送**即時通知**。 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。 這應該是一個可以處理 POST 請求的公開訪問的 URL。
|
||
4. **保存：** 點擊 **保存** 來創建 webhook。 新的 webhook 將立即生效。 新的 webhook 將立即生效。
|
||
|
||
如果需要通過不同的端點發送不同的事件，可以創建多個 webhook。 如果需要通過不同的端點發送不同的事件，可以創建多個 webhook。 每一個 webhook 本質上都是對所有相關事件的訂閱（目前，Twenty 將所有事件類型發送到給定的 URL；在 UI 中可能配置過濾特定事件類型）。 如果需要刪除某個 webhook，您可以從相同的設置頁面刪除它（選擇 webhook，然後選擇刪除）。 如果需要刪除某個 webhook，您可以從相同的設置頁面刪除它（選擇 webhook，然後選擇刪除）。
|
||
|
||
## Events and Payloads
|
||
|
||
設置好 webhook 後，當您的 CRM 數據中發生觸發事件時，Twenty 會向您指定的 URL 發送 HTTP POST 請求。 常見的觸發 webhook 的事件包括： 常見的觸發 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. 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 的範例：
|
||
|
||
```javascript
|
||
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");
|
||
``` |