Tổng quan về webhook

Sursa ghi lại một sự kiện cho mỗi thay đổi quan trọng: một thẻ được xuất bản, được kiểm chứng hoặc được lưu trữ, một thông báo được đọc, một câu hỏi không có câu trả lời. Bạn có thể nhận sự kiện theo hai cách và dùng cả hai cùng lúc:

	Webhook	Nguồn cấp sự kiện
Cách thức	Sursa gửi từng sự kiện tới địa chỉ HTTPS của bạn ngay khi nó xảy ra.	Bạn đọc `GET /v1/webhook-events` khi bạn muốn.
Độ trễ	Vài giây.	Tùy theo tần suất bạn thăm dò.
Cần có	Một máy chủ nhận HTTPS công khai.	Chỉ cần khóa API có vai trò `admin` và phạm vi quyền `webhooks:manage`.
Phù hợp cho	Phản ứng với thay đổi: thông báo, đồng bộ, khởi chạy một quy trình tự động.	Tác vụ theo lô, bắt kịp sau thời gian ngừng hoạt động, đối soát.

Cả hai mang cùng các sự kiện với cùng ID. Mọi sự kiện được lưu giữ trong nguồn cấp trong 30 ngày, dù có webhook nào đăng ký nhận nó hay không.

Sự kiện

{
  "id": "evt_0123456789abcdef0123456789abcdef",
  "type": "card.updated",
  "created_at": "2026-10-24T10:00:03Z",
  "org_id": 1,
  "api_version": "1.60.0",
  "sequence": 1042,
  "object": {"type": "card", "id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60"},
  "payload": "full",
  "data": {
    "card": {"id": "3f2c9a7e-5b1d-4c8e-9f0a-1b2c3d4e5f60", "title": "Refund policy", "collection": "support", "version": 4},
    "actor_id": 7,
    "previous_attributes": {"title": "Refunds"}
  },
  "test": false
}

Trường	Ý nghĩa
`id`	ID của sự kiện, gồm `evt_` và 32 ký tự thập lục phân. Giống nhau trong mọi lần thử gửi và trong nguồn cấp.
`type`	Điều gì đã xảy ra, dạng `<object>.<past-tense verb>`: `card.updated`, `access_request.resolved`.
`created_at`	Thời điểm thay đổi xảy ra, theo UTC.
`api_version`	Phiên bản API mà lược đồ của `data` tuân theo.
`object`	Loại và ID của đối tượng mà sự kiện nói tới.
`data`	Chi tiết. Dạng của nó phụ thuộc vào loại sự kiện và được mô tả trong catalog sự kiện.
`data.previous_attributes`	Trong các sự kiện `*.updated`: giá trị trước đó của các trường đã thay đổi.
`sequence`, `payload`, `test`	Chỉ có trong các lần gửi webhook: vị trí trong thứ tự gửi của webhook, chế độ payload, và đây có phải sự kiện thử hay không.

data chỉ chứa những gì mà bất kỳ người đọc nào của đối tượng cũng có thể xem qua API. Nó không bao giờ chứa danh sách quyền truy cập, quyền của người khác hay các trường ẩn. Lý do trong sự kiện là các mã trung tính ngắn như no_hits, restricted hoặc index_failed.

Loại sự kiện

Sự kiện bao quát các lĩnh vực sau:

Lĩnh vực	Ví dụ
Thẻ	`card.created`, `card.updated`, `card.published`, `card.archived`, `card.deleted`, `card.indexed`, `card.index_failed`
Kiểm chứng	`card.verified`, `card.unverified`, `verification.expired`, `verification.requested`
Cấu trúc	`collection.created`, `folder.updated`
Cộng tác	`comment.created`, `draft.publish_requested`, `announcement.sent`, `announcement.read`
Câu trả lời	`question.unanswered`, `question.feedback_created`, `access_request.created`
Người dùng và quyền truy cập	`user.created`, `user.deactivated`, `group.member_added`, `api_key.expiring`
Nguồn và nhập dữ liệu	`source.sync_completed`, `import.sync_completed`, `import.document_failed`
Tác vụ	`job.completed`, `job.failed`, `export.ready`
Webhook	`webhook.endpoint_disabled`, `webhook.ping`

Danh sách đầy đủ kèm lược đồ và ví dụ của từng sự kiện có trong catalog sự kiện của tài liệu tham chiếu API. GET /v1/webhooks/catalog trả về các loại sự kiện có trên bản cài đặt của bạn.

Theo thời gian, loại sự kiện mới được bổ sung và các sự kiện hiện có có thêm trường. Loại sự kiện không bao giờ bị đổi tên hoặc bị xóa. Máy chủ nhận của bạn phải bỏ qua các loại và trường mà nó không biết.

Ai nhận được gì

Một webhook chỉ nhận sự kiện nếu đối tượng của sự kiện hiển thị với webhook đó, theo cùng cách như với khóa API: theo vai trò, hồ sơ dữ liệu và bộ sưu tập của nó. Webhook giới hạn trong bộ sưu tập support không bao giờ nhận sự kiện về thẻ trong finance. Sự kiện về người dùng, khóa, nguồn, lượt nhập, tác vụ, lượt xuất, thanh toán, ứng dụng và chính các webhook chỉ được gửi tới webhook có vai trò admin.

Trong phạm vi đó, mỗi webhook tự chọn sự kiện của mình:

theo loại, với mẫu: card.* cho mọi sự kiện về thẻ, * cho mọi sự kiện;
theo bộ sưu tập và theo nhãn, đối với sự kiện về thẻ.

Chế độ payload của webhook là full (sự kiện có data, mặc định) hoặc thin (sự kiện không có data: máy chủ nhận của bạn đọc đối tượng qua API bằng khóa của chính nó, và luôn thấy trạng thái hiện tại của đối tượng).

Tóm tắt về việc gửi

Một yêu cầu HTTPS POST với sự kiện dạng JSON, được ký bằng khóa bí mật của webhook theo hai định dạng: Standard Webhooks (webhook-signature) và X-KB-Signature trước đây.
Mọi câu trả lời 2xx trong vòng 10 giây đều được coi là thành công.
Lần gửi thất bại được thử lại trong gần ba ngày với khoảng chờ tăng dần. Retry-After trong câu trả lời 429 hoặc 503 được tôn trọng; 410 vô hiệu hóa webhook; 10 lần thất bại liên tiếp tạm dừng webhook cho tới khi nó được tiếp tục.
Các lần gửi tới một webhook được gửi theo đúng thứ tự. Một webhook chậm không làm trễ các webhook khác.
Cùng một sự kiện có thể tới nhiều hơn một lần: hãy loại bỏ bản trùng lặp theo webhook-id.

Nhận webhook hướng dẫn từng bước xây dựng một máy chủ nhận hoàn chỉnh, có kiểm tra chữ ký bằng Node.js, Python và Go.

Quản lý webhook

Việc cần làm	Endpoint
Tạo webhook và nhận khóa bí mật của nó	`POST /v1/webhooks`
Thay đổi địa chỉ, sự kiện hoặc trạng thái	`PATCH /v1/webhooks/{webhook_id}`
Gửi sự kiện thử	`POST /v1/webhooks/{webhook_id}/test`
Xoay vòng khóa bí mật	`POST /v1/webhooks/{webhook_id}/rotate-secret`
Tiếp tục webhook đang bị tạm dừng	`POST /v1/webhooks/{webhook_id}/resume`
Xem các lần gửi và câu trả lời	`GET /v1/webhooks/{webhook_id}/deliveries`
Gửi lại một lần gửi	`POST /v1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver`

Việc quản lý webhook cần khóa có vai trò admin và phạm vi quyền webhooks:manage, hoặc quản trị viên trong giao diện quản trị. Một tổ chức có thể có tối đa 20 webhook. Webhook là một phần của gói của tổ chức; nếu gói không có, các endpoint này trả về 403 với mã webhooks.feature_disabled.