8cadd00d34
Created by Github action --------- Co-authored-by: Crowdin Bot <support+bot@crowdin.com> Co-authored-by: github-actions <github-actions@twenty.com>
87 lines
6.2 KiB
Plaintext
87 lines
6.2 KiB
Plaintext
---
|
|
title: Webhooks
|
|
image: /images/docs/getting-started/webhooks.png
|
|
info: Khám phá cách sử dụng Webhooks của chúng tôi.
|
|
---
|
|
|
|
<Frame>
|
|
<img src="/images/docs/getting-started/webhooks.png" alt="Header" />
|
|
</Frame>
|
|
|
|
## Tổng quan
|
|
|
|
Webhooks trong Twenty bổ sung cho API bằng cách cho phép **thông báo theo thời gian thực** tới các ứng dụng của bạn khi có sự kiện xảy ra trong CRM của bạn. Thay vì liên tục hỏi API về các thay đổi, bạn có thể thiết lập webhooks để Twenty **đẩy** dữ liệu tới hệ thống của bạn bất cứ khi nào sự kiện cụ thể xảy ra (ví dụ: khi một bản ghi mới được tạo hoặc một bản ghi hiện có được cập nhật). Điều này giúp các hệ thống bên ngoài đồng bộ với Twenty ngay lập tức và hiệu quả.
|
|
|
|
Với webhooks, Twenty sẽ gửi một yêu cầu HTTP POST tới một URL mà bạn chỉ định, chứa thông tin chi tiết về sự kiện. You can then handle that data in your application (e.g., to update your external database, trigger workflows, or send alerts).
|
|
|
|
## Thiết lập một Webhook
|
|
|
|
Để tạo một webhook trong Twenty, sử dụng cài đặt **APIs & Webhooks** trong ứng dụng Twenty của bạn:
|
|
|
|
1. **Điều hướng đến Cài đặt:** Trong ứng dụng Twenty của bạn, vào **Cài đặt → APIs & Webhooks**.
|
|
2. **Tạo một Webhook:** Dưới **Webhooks** nhấp vào **+ Tạo webhook**.
|
|
3. **Nhập URL:** Cung cấp URL điểm cuối trên máy chủ của bạn nơi bạn muốn Twenty gửi yêu cầu webhook. Đây nên là một URL công khai có thể xử lý các yêu cầu POST.
|
|
4. **Lưu:** Nhấp **Lưu** để tạo webhook. Webhook mới sẽ hoạt động ngay lập tức.
|
|
|
|
Bạn có thể tạo nhiều webhooks nếu bạn cần gửi các sự kiện khác nhau tới các điểm cuối khác nhau. Mỗi webhook về cơ bản là một đăng ký cho tất cả các sự kiện liên quan (hiện tại, Twenty gửi tất cả các loại sự kiện tới URL đã cho; lọc các loại sự kiện cụ thể có thể được cấu hình qua giao diện người dùng). Nếu bạn cần xóa một webhook, bạn có thể xóa nó từ cùng trang cài đặt (chọn webhook và chọn xóa).
|
|
|
|
## Sự kiện và Payloads
|
|
|
|
Sau khi một webhook được thiết lập, Twenty sẽ gửi một yêu cầu HTTP POST tới URL bạn đã chỉ định mỗi khi có sự kiện kích hoạt xảy ra trong dữ liệu CRM của bạn. Những sự kiện phổ biến kích hoạt webhooks bao gồm:
|
|
|
|
- **Bản ghi được tạo:** ví dụ, thêm một người mới (\"person.created\"), tạo một công ty mới (\"company.created\"), tạo một ghi chú (\"note.created\"), vv.
|
|
- **Bản ghi được cập nhật:** ví dụ, thông tin một người hiện có được cập nhật (\"person.updated\"), hồ sơ công ty được chỉnh sửa (\"company.updated\"), vv.
|
|
- **Bản ghi bị xóa:** ví dụ, một người hoặc công ty bị xóa (\"person.deleted\", \"company.deleted\").
|
|
- **Các sự kiện khác:** Nếu áp dụng, các sự kiện đối tượng khác hoặc kích hoạt tùy chỉnh (chẳng hạn như, nếu các tác vụ hoặc đối tượng khác được cập nhật, các loại sự kiện tương tự sẽ được sử dụng như \"task.created\", \"note.updated\", v.v.).
|
|
|
|
Yêu cầu POST webhook chứa một payload JSON trong nội dung của nó. Payload sẽ thường bao gồm ít nhất hai thứ: loại sự kiện và dữ liệu liên quan đến sự kiện đó (thường là bản ghi đã được tạo/cập nhật). Ví dụ, một webhook cho một người mới được tạo có thể gửi một payload như sau:
|
|
|
|
```
|
|
{
|
|
"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"
|
|
}
|
|
```
|
|
|
|
Trong ví dụ này:
|
|
|
|
- `\"event\"` chỉ định điều gì đã xảy ra (`person.created`).
|
|
- `\"data\"` chứa thông tin chi tiết về bản ghi mới (thông tin bạn sẽ nhận được nếu bạn yêu cầu người đó thông qua API).
|
|
- `\"timestamp\"` là khi sự kiện xảy ra (theo UTC).
|
|
|
|
Điểm cuối của bạn nên chuẩn bị để nhận những dữ liệu JSON như vậy qua POST. Thông thường, bạn sẽ phân tích dữ liệu JSON, nhìn vào loại sự kiện `\"event\"` để hiểu điều gì đã xảy ra, và sau đó sử dụng `\"data\"` theo cách phù hợp (ví dụ, tạo một liên lạc mới trong hệ thống của bạn, hoặc cập nhật một liên lạc hiện có).
|
|
|
|
**Lưu ý:** Điều quan trọng là đáp lại bằng trạng thái HTTP **2xx** từ điểm cuối webhook của bạn để xác nhận đã nhận thành công. Nếu người gửi webhook của Twenty không nhận được phản hồi 2xx, nó có thể xem xét việc gửi thất bại. (Trong tương lai, logic thử lại có thể cố gắng gửi lại webhooks bị thất bại, vì vậy luôn cố gắng trả về một 200 OK càng nhanh càng tốt sau khi xử lý dữ liệu.)
|
|
|
|
## Xác thực Webhook
|
|
|
|
Để đảm bảo an toàn cho các điểm cuối webhook của bạn, Twenty bao gồm một chữ ký trong tiêu đề `X-Twenty-Webhook-Signature`.
|
|
|
|
Chữ ký này là một băm HMAC SHA256 của payload yêu cầu, được tính toán bằng cách sử dụng bí mật webhook của bạn.
|
|
|
|
Để xác thực chữ ký, bạn cần:
|
|
|
|
1. Kết hợp thời gian (từ tiêu đề `X-Twenty-Webhook-Timestamp`), một dấu hai chấm, và chuỗi JSON của payload
|
|
2. Tính toán băm HMAC SHA256 sử dụng bí mật webhook của bạn làm khóa
|
|
3. So sánh mã hex tạo ra với tiêu đề chữ ký
|
|
|
|
Đây là một ví dụ trong 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");
|
|
``` |