Các sự kiện Webhook và nội dung của chúng

Mỗi sự kiện webhook Notiondesk bạn có thể chọn, định dạng yêu cầu mà máy chủ của bạn nhận được và dữ liệu chứa trong mỗi sự kiện.

15 phút đọc

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.

Hướng dẫn nhanh: Chọn sự kiện trong Cài đặt > Nhà phát triển > Webhooks , mục Sự kiện trên một điểm cuối. Mỗi yêu cầu là một JSON với các tham số , , , , và .POSTideventversionoccurred_atsite_iddata

Cá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ảnarticle.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óaarticle.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óacategory.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ảnchangelog.published
Đồng bộ hóa hoàn tất Quá trình đồng bộ hóa với Notion hoàn tấtsync.completed
Đồng bộ hóa thất bại Quá trình đồng bộ với Notion thất bạisync.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ưusite.updated
Mã tùy chỉnh đã được lưu CSS hoặc JavaScript tùy chỉnh được lưusite.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úpsite.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ốinotion.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 chatbotchatbot.guidance.created
Hướng dẫn sử dụng chatbot đã được cập nhật. Hướng dẫn thay đổichatbot.guidance.updated
Hướng dẫn của chatbot đã bị xóa Một hướng dẫn đã bị xóachatbot.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 đổiredirect.updated
Chuyển hướng đã bị xóa Lệnh chuyển hướng đã bị xóaredirect.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ốiworkspace.join_request.declined
Đồng đội được mời Một đồng đội được mờiteam_member.invited
Đồng đội đã gia nhập Một đồng đội được mời chấp nhậnteam_member.joined
Vai trò của đồng đội đã thay đổi Vai trò của một đồng đội thay đổiteam_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ạoapi_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 rasite.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ì?
idMã đị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.
eventTên sự kiện, ví dụ: article.published
versionPhiên bản của định dạng yêu cầu này
occurred_atThời điểm sự kiện xảy ra, được ghi lại theo định dạng ngày và giờ ISO 8601.
site_idTrung 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ử.
dataNhữ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-Typeapplication/json
User-AgentND-Webhooks/1.0
X-ND-EventTên sự kiện, giống như event trong phần thân.
X-ND-DeliveryMã đị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-SignatureChữ 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.createdcontact_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.translatedarticle 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.createdarticle: 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.completedsync: trigger, duration_seconds, pages_synced, pages_updated
sync.failedsync: 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.updatedcustom_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.updatedintegration: type, enabled
notion.connected, notion.disconnected, notion.access_lost Một đối tượng rỗng, {}
chatbot.updatedchatbot: 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.updatedworkspace: 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_inuser: 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.rotatedapi_key cho khóa mới và previous_api_key: id
pingmessage

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ỳ id nà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_at khi 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.

Bài viết liên quan

Trang này có hữu ích không?

Still need help? Ask us