Mỗi yêu cầu webhook cho bạn biết điều gì đã xảy ra trong không gian làm việc của bạn hoặc một trong các trung tâm trợ giúp của nó. Bài viết này liệt kê mọi sự kiện bạn có thể chọn cho một điểm cuối, hình thức của mỗi yêu cầu và nội dung mà nó chứa.
POSTideventversionoccurred_atsite_iddataCác sự kiện bạn có thể lựa chọn
Bảng điều khiển nhóm các sự kiện theo cùng một cách như các bảng bên dưới. Cột đầu tiên là tên bạn thấy trong trình chọn sự kiện. Cột thứ hai là tên sự kiện mà máy chủ của bạn nhận được trong event.
Liên hệ
| Trên bảng điều khiển | Sự kiện | Đã gửi khi |
|---|---|---|
| Đã nhận được tin nhắn liên hệ | Một khách truy cập gửi biểu mẫu liên hệ của bạn. | contact_message.created |
Nội dung
| Trên bảng điều khiển | Sự kiện | Đã gửi khi |
|---|---|---|
| Bài viết đã được tạo | Một bài viết mới, hoặc một phiên bản ngôn ngữ mới của bài viết, đã được thêm vào. | article.created |
| Bài viết đã được cập nhật. | Nội dung bài viết thay đổi trong quá trình đồng bộ hóa. | article.updated |
| Bài báo đã được xuất bản | Ngôn ngữ của bài báo được xuất bản | article.published |
| Bài báo chưa được xuất bản | Ngôn ngữ đã xuất bản của bài báo không còn được xuất bản nữa. | article.unpublished |
| Bài viết đã bị xóa | Bài viết đã bị xóa | article.deleted |
| Bài viết đã được dịch | Bài viết được dịch tự động sang ngôn ngữ mới. | article.translated |
| Phản ứng được thêm vào | Một độc giả phản hồi về bài báo. | article.reaction.added |
| Phản ứng đã thay đổi | Người đọc thay đổi phản ứng của họ | article.reaction.changed |
| Phản ứng đã bị loại bỏ | Người đọc loại bỏ phản ứng của họ | article.reaction.removed |
| Đã nhận được phản hồi về bài viết | Một độc giả gửi phản hồi bằng văn bản về bài báo. | article.feedback.created |
| Danh mục đã được tạo | Một danh mục mới, hoặc một ngôn ngữ mới thuộc danh mục đó, được thêm vào. | category.created |
| Danh mục đã được cập nhật | Nội dung của một danh mục thay đổi trong quá trình đồng bộ hóa. | category.updated |
| Danh mục đã bị xóa | Một danh mục đã bị xóa | category.deleted |
| Mục nhật ký thay đổi đã được xuất bản | Một bài viết trong danh mục nhật ký thay đổi đã được xuất bản | changelog.published |
| Đồng bộ hóa hoàn tất | Quá trình đồng bộ hóa với Notion hoàn tất | sync.completed |
| Đồng bộ hóa thất bại | Quá trình đồng bộ với Notion thất bại | sync.failed |
Các sự kiện article.updated và category.updated không được gửi khi chỉ có trạng thái hoặc các thuộc tính khác thay đổi. Sự kiện danh mục được gửi một lần cho mỗi ngôn ngữ.
Số lượng phản hồi và bình luận bài viết được giới hạn ở mức 120 sự kiện mỗi phút cho mỗi trung tâm trợ giúp. Các sự kiện vượt quá giới hạn sẽ không được gửi đi, vì vậy hãy sử dụng công cụ phân tích trung tâm trợ giúp của bạn để biết tổng số.
Cài đặt trung tâm trợ giúp
| Trên bảng điều khiển | Sự kiện | Đã gửi khi |
|---|---|---|
| Cài đặt trung tâm trợ giúp đã được lưu | Một cài đặt trung tâm trợ giúp đã được lưu | site.updated |
| Mã tùy chỉnh đã được lưu | CSS hoặc JavaScript tùy chỉnh được lưu | site.custom_code.updated |
| Tên miền tùy chỉnh đã được xác minh | Tên miền tùy chỉnh của bạn bắt đầu phục vụ trung tâm trợ giúp | site.domain.verified |
| Kiểm tra tên miền tùy chỉnh thất bại | Không thể truy cập tên miền tùy chỉnh của bạn. | site.domain.verification_failed |
| Đã cập nhật tích hợp | Một quá trình tích hợp được thiết lập, thay đổi, bật hoặc tắt. | integration.updated |
| Notion đã kết nối | Ý tưởng được kết nối | notion.connected |
| Khái niệm bị ngắt kết nối | Khái niệm này đã bị ngắt kết nối. | notion.disconnected |
| Mất quyền truy cập Notion | Notiondesk không thể đọc trang Notion của bạn nữa. | notion.access_lost |
| Chatbot AI đã được cập nhật | Các cài đặt của chatbot thay đổi, hoặc nó được bật hoặc tắt. | chatbot.updated |
| Hướng dẫn chatbot đã được thêm vào. | Hướng dẫn được thêm vào chatbot | chatbot.guidance.created |
| Hướng dẫn sử dụng chatbot đã được cập nhật. | Hướng dẫn thay đổi | chatbot.guidance.updated |
| Hướng dẫn của chatbot đã bị xóa | Một hướng dẫn đã bị xóa | chatbot.guidance.deleted |
| Đã thêm chuyển hướng | Một lệnh chuyển hướng đã được thêm vào. | redirect.created |
| Đã cập nhật chuyển hướng | Việc chuyển hướng thay đổi | redirect.updated |
| Chuyển hướng đã bị xóa | Lệnh chuyển hướng đã bị xóa | redirect.deleted |
Các tên miền tùy chỉnh được kiểm tra thường xuyên, vì vậy các sự kiện liên quan đến tên miền có thể xuất hiện vài phút sau khi thay đổi.
Không gian làm việc
Các sự kiện trong không gian làm việc không được liên kết với một trung tâm trợ giúp cụ thể nào, vì vậy site_id của chúng là null.
| Trên bảng điều khiển | Sự kiện | Đã gửi khi |
|---|---|---|
| Không gian làm việc được đổi tên | Không gian làm việc được đổi tên. | workspace.updated |
| Đã nhận được yêu cầu tham gia | Có người yêu cầu được tham gia không gian làm việc. | workspace.join_request.created |
| Yêu cầu tham gia đã được chấp thuận | Yêu cầu tham gia đã được chấp thuận. | workspace.join_request.approved |
| Yêu cầu tham gia bị từ chối | Yêu cầu tham gia bị từ chối | workspace.join_request.declined |
| Đồng đội được mời | Một đồng đội được mời | team_member.invited |
| Đồng đội đã gia nhập | Một đồng đội được mời chấp nhận | team_member.joined |
| Vai trò của đồng đội đã thay đổi | Vai trò của một đồng đội thay đổi | team_member.role_changed |
| Đồng đội được bật hoặc tắt | Một đồng đội đang được bật hoặc tắt. | team_member.status_changed |
| Đồng đội đã bị loại bỏ | Một đồng đội bị loại khỏi đội. | team_member.removed |
| Đồng đội đã đăng nhập | Một đồng đội đăng nhập. Chỉ được gửi đến không gian làm việc mà họ mở theo mặc định. | team_member.logged_in |
| Khóa API đã được tạo | Một khóa API được tạo | api_key.created |
| Khóa API đã được xoay vòng | Khóa API được xoay vòng. | api_key.rotated |
| Khóa API đã bị thu hồi | Khóa API đã bị thu hồi. | api_key.revoked |
| Trung tâm trợ giúp đã được tạo | Một trung tâm trợ giúp được tạo ra | site.created |
| Trung tâm trợ giúp đã bị xóa | Trung tâm trợ giúp bị xóa trong khi không gian làm việc vẫn còn một trung tâm trợ giúp trực tuyến khác. | site.deleted |
Sự kiện thử nghiệm
| Trên bảng điều khiển | Sự kiện | Đã gửi khi |
|---|---|---|
| Sự kiện thử nghiệm | Bạn nhấp vào "Gửi sự kiện kiểm thử" trên một điểm cuối. | ping |
Bạn không thể chọn ping trong danh sách sự kiện. Nó chỉ được gửi đến điểm cuối mà bạn kiểm tra, site_id của nó là null, và nó được gửi một lần, không có lần thử lại nào.
Mỗi yêu cầu chứa những gì?
Notiondesk gửi yêu cầu POST với nội dung JSON:
{
"id": "019a8f2e-4b1c-7d3e-9f40-5a6b7c8d9e01",
"event": "article.published",
"version": "2026-11-06",
"occurred_at": "2026-11-17T14:32:05+00:00",
"site_id": "019a8f2e-0b7d-7c3a-9e15-4f2a6b8c0d11",
"data": {
"article": {
"id": "1763391842",
"locale": "en",
"title": "Reset your password",
"slug": "reset-your-password",
"url": "https://help.acme-support.com/en/articles/reset-your-password",
"status": "published"
}
}
}| Cánh đồng | Nó là gì? |
|---|---|
id | Mã định danh (ID) của sự kiện. Mã này vẫn giữ nguyên khi yêu cầu được thử lại, vì vậy hãy sử dụng nó để phát hiện các sự kiện trùng lặp. |
event | Tên sự kiện, ví dụ: article.published |
version | Phiên bản của định dạng yêu cầu này |
occurred_at | Thời điểm sự kiện xảy ra, được ghi lại theo định dạng ngày và giờ ISO 8601. |
site_id | Trung tâm trợ giúp mà sự kiện xuất phát từ đó, hoặc null đối với các sự kiện không gian làm việc và sự kiện kiểm thử. |
data | Những nội dung mà sự kiện đề cập đến. Xem Dữ liệu chứa gì |
Mỗi yêu cầu cũng mang theo các tiêu đề sau:
| Tiêu đề | Giá trị |
|---|---|
Content-Type | application/json |
User-Agent | ND-Webhooks/1.0 |
X-ND-Event | Tên sự kiện, giống như event trong phần thân. |
X-ND-Delivery | Mã định danh (ID) của lần gửi hàng này đến điểm cuối này. Mã này vẫn giữ nguyên trong suốt các lần thử lại. |
X-ND-Signature | Chữ ký chứng minh yêu cầu đến từ Notiondesk. Việc kiểm tra này được đề cập trong phần Xác minh rằng webhook đến từ Notiondesk. |
Dữ liệu chứa gì?
data chứa một hoặc nhiều đối tượng, tùy thuộc vào sự kiện:
| Sự kiện | Bên trong data có gì? |
|---|---|
contact_message.created | contact_message: id, name, email, subject, message, locale |
article.created, article.updated, article.published, article.unpublished, changelog.published | article: id, locale, title, slug, url, status |
article.translated | article trong ngôn ngữ mới và source_locale |
article.deleted | __ĐÃ BẢO TỒN_195__: __ĐÃ BẢO TỒN_194__ |
article.reaction.added, article.reaction.changed, article.reaction.removed | article: id và reaction: type |
article.feedback.created | article: id, và feedback: id, name, email, message, locale |
| __ĐƯỢC BẢO TỒN_177__, __ĐƯỢC BẢO TỒN_176__ | category: id, locale, name, slug |
category.deleted | __ĐÃ BẢO TỒN_169__: __ĐÃ BẢO TỒN_168__ |
sync.completed | sync: trigger, duration_seconds, pages_synced, pages_updated |
sync.failed | sync: reason, pages_processed |
| __ĐÃ BẢO TỒN_157__, __ĐÃ BẢO TỒN_156__ | site: id, name, url |
site.deleted | __ĐÃ BẢO TỒN_150__: __ĐÃ BẢO TỒN_149__ |
site.custom_code.updated | custom_code: type (css hoặc js) |
| __ĐÃ BẢO TỒN_143__, __ĐÃ BẢO TỒN_142__ | __ĐÃ BẢO TỒN_141__: __ĐÃ BẢO TỒN_140__ |
integration.updated | integration: type, enabled |
notion.connected, notion.disconnected, notion.access_lost | Một đối tượng rỗng, {} |
chatbot.updated | chatbot: id, name, enabled |
| __ĐÃ BẢO TỒN_126__, __ĐÃ BẢO TỒN_125__ | guidance: id, type, title, enabled |
chatbot.guidance.deleted | __ĐÃ BẢO TỒN_118__: __ĐÃ BẢO TỒN_117__ |
| __ĐÃ BẢO TỒN_116__, __ĐÃ BẢO TỒN_115__ | redirect: id, source_path, type, article_id, category_id |
redirect.deleted | __ĐÃ BẢO TỒN_107__: __ĐÃ BẢO TỒN_106__ |
workspace.updated | workspace: id, name |
workspace.join_request.created, .approved, .declined | join_request: id, email, status |
team_member.invited, .joined, .role_changed, .status_changed | team_member: id, email, role, status |
team_member.removed | __ĐÃ BẢO TỒN_84__: __ĐÃ BẢO TỒN_83__ |
team_member.logged_in | user: id, email, name |
| __ĐƯỢC BẢO TỒN_77__, __ĐƯỢC BẢO TỒN_76__ | api_key: id, prefix, label, scopes, expires_at |
api_key.rotated | api_key cho khóa mới và previous_api_key: id |
ping | message |
data không bao giờ chứa tệp đính kèm, thông tin bí mật, mã tùy chỉnh hoặc chi tiết thanh toán.
Ví dụ dữ liệu theo nhóm sự kiện
Các ví dụ này chỉ hiển thị data. Phần còn lại của yêu cầu là giống nhau đối với mọi sự kiện.
Mẫu liên hệ, contact_message.created:
Bài viết, __ĐƯỢC BẢO TỒN_60__:
status là trạng thái của ngôn ngữ đó: draft, review, published, archived hoặc translation source. url có thể là null nếu trung tâm trợ giúp chưa có địa chỉ.
Phản hồi và ý kiến đóng góp, article.feedback.created:
Đối với các phản hồi, reaction.type sẽ là smiley, neutral_face hoặc disappointed. Các trung tâm trợ giúp hiển thị nút biểu tượng ngón tay cái sẽ gửi smiley cho Có và disappointed cho Không. Về phản hồi, article.id sẽ là null khi bài viết không còn tồn tại.
Danh mục, __ĐÃ BẢO TỒN_42__:
Đồng bộ hóa, sync.completed và sync.failed:
trigger là manual, api hoặc automatic. reason là pages_failed khi một số trang không thể đồng bộ hóa, hoặc failed khi quá trình đồng bộ hóa dừng lại.
Cài đặt trung tâm trợ giúp, redirect.created:
Không gian làm việc và đồng đội, team_member.role_changed:
role là admin, editor, billing_manager hoặc viewer. status là enabled, disabled hoặc pending_invite.
Khóa API, api_key.rotated:
Sự kiện thử nghiệm, ping:
Xử lý các sự kiện trong bộ thu của bạn
{
"contact_message": {
"id": "019a8f31-5c2e-7a41-8b9d-2e6f0a7c4b23",
"name": "Jamie Rivera",
"email": "[email protected]",
"subject": "Invoice question",
"message": "Hi, where can I download my latest invoice?",
"locale": "en"
}
}{
"article": {
"id": "1763391842",
"locale": "fr",
"title": "Réinitialiser votre mot de passe",
"slug": "reinitialiser-votre-mot-de-passe",
"url": "https://help.acme-support.com/fr/articles/reinitialiser-votre-mot-de-passe",
"status": "published"
},
"source_locale": "en"
}{
"article": { "id": "1763391842" },
"feedback": {
"id": "019a8f33-8d4f-7b52-a1c3-6e9b2d0f7a35",
"name": "Sam Lee",
"email": "[email protected]",
"message": "The screenshots don't match the new settings page.",
"locale": "en"
}
}{
"category": {
"id": "1763392017",
"locale": "en",
"name": "Billing",
"slug": "billing"
}
}{
"sync": {
"trigger": "automatic",
"duration_seconds": 42,
"pages_synced": 120,
"pages_updated": 3
}
}{
"sync": {
"reason": "pages_failed",
"pages_processed": 118
}
}{
"redirect": {
"id": "019a8f35-2a6c-7d63-b4e8-0c1f5a9d3e47",
"source_path": "/old-help/reset-password",
"type": "article",
"article_id": "1763391842",
"category_id": null
}
}{
"team_member": {
"id": "019a8f37-7e1b-7f74-8c2d-9a4e6b1f0c59",
"email": "[email protected]",
"role": "editor",
"status": "enabled"
}
}{
"api_key": {
"id": "019a8f39-3f8a-7185-9d6e-1b7c4e2a8d6b",
"prefix": "nd_wsk_4fa9c2e17b30",
"label": "CRM sync",
"scopes": ["read"],
"expires_at": null
},
"previous_api_key": { "id": "0199c4d2-6b3e-7296-ae0f-5d8a1c7e9b7d" }
}{
"message": "Test event from Notiondesk."
}- Phản hồi nhanh chóng. Trước tiên, hãy trả về mã trạng thái
2xx, sau đó mới thực hiện công việc. Notiondesk chờ 5 giây để máy chủ của bạn bắt đầu phản hồi và tổng cộng 10 giây, và chỉ đọc mã trạng thái.
- Hãy lưu ý rằng sẽ có các sự kiện trùng lặp. Cùng một sự kiện có thể xuất hiện nhiều hơn một lần, ví dụ như sau khi thử lại. Bỏ qua bất kỳ
idnào bạn đã xử lý.
- Đừng quá phụ thuộc vào thứ tự. Các sự kiện có thể xảy ra không theo thứ tự. Hãy sử dụng
occurred_atkhi thứ tự là quan trọng.
- Đọc dữ liệu ở trạng thái mới nhất.
datađược đọc khi sự kiện được gửi đi, vì vậy hai thay đổi nhanh chóng đối với một bài viết đều có thể mang theo phiên bản mới hơn. Nếu mục đó đã biến mất trước thời điểm đó, sự kiện sẽ bị bỏ qua.
Câu hỏi thường gặp
Tôi có nhận được toàn bộ nội dung bài viết không?
Không. Sự kiện bài viết chứa tiêu đề, slug, URL và trạng thái. Sử dụng API Notiondesk nếu bạn cần thêm thông tin.
Làm sao tôi biết được sự kiện đó đến từ trung tâm hỗ trợ nào?
Đọc site_id. Đây là ID của trung tâm trợ giúp, hoặc null cho các sự kiện không gian làm việc và sự kiện kiểm thử.
Tại sao tôi không nhận được sự kiện nào cho mỗi phản ứng?
Số lượng phản hồi và bình luận bài viết được giới hạn ở mức 120 sự kiện mỗi phút cho mỗi trung tâm trợ giúp. Các sự kiện vượt quá giới hạn sẽ không được gửi đi. Vui lòng sử dụng công cụ phân tích trung tâm trợ giúp để xem tổng số.
Tôi có thể nhận cùng một sự kiện hai lần không?
Vâng, ví dụ như sau khi thử lại. id vẫn giữ nguyên, vì vậy hãy bỏ qua mục bạn đã xử lý.
"Phiên bản" có nghĩa là gì?
Nó cho bạn biết định dạng yêu cầu nào đã được sử dụng. Các yêu cầu hiện đang sử dụng 2026-11-06.