Chuyển tới nội dung
Sursa Developers

GET/v1/webhook-events

Liệt kê sự kiện

list_webhook_events

Trả về các sự kiện của tổ chức trong 30 ngày gần nhất, bất kể có webhook nào đăng ký nhận chúng hay không: dùng thao tác này để đồng bộ mà không cần webhook hoặc để bắt kịp các sự kiện mà máy chủ nhận đã bỏ lỡ sau sự cố. Sự kiện được sắp xếp tăng dần, giống như nhật ký. next_cursor luôn được trả về, kể cả khi has_more là false: hãy lưu nó và tiếp tục thăm dò từ cùng vị trí. Sự kiện xuất hiện trong nguồn cấp khi đã được đưa vào hàng đợi gửi webhook, thường chưa đến một giây sau khi thay đổi. Sự kiện có cùng dạng với phần thân của lần gửi webhook nhưng không có các trường của lần gửi. Cần quyền ORG_MANAGE_KEYS; khóa API cần phạm vi đọc. Được thêm trong 1.62.0.

Xác thực

Gửi khóa API trong header Authorization: Authorization: Bearer <khóa>.

Tham số truy vấn

  • limitinteger

    Số sự kiện trên một trang.

    Mặc định: 50≥ 1, ≤ 200

  • cursorstring

    next_cursor từ phản hồi trước với cùng bộ lọc. Khi không có con trỏ, nguồn cấp bắt đầu từ đầu thời hạn lưu giữ.

    length ≤ 512

  • typearray of string

    Loại sự kiện hoặc mặt nạ miền (card.* khớp mọi sự kiện thẻ, * khớp mọi sự kiện). Lặp lại tối đa 20 lần.

    items ≤ 20

  • object_typestring

    Loại đối tượng của sự kiện (card, draft, announcement, question).

    length ≤ 64

  • object_idstring

    ID của đối tượng của sự kiện, ví dụ một thẻ.

    length ≤ 200

  • created_sincestring (date-time)

    Các sự kiện tại hoặc sau thời điểm này (tính cả thời điểm này), theo RFC 3339 có độ lệch múi giờ.

  • created_untilstring (date-time)

    Các sự kiện trước thời điểm này (không tính thời điểm này), theo RFC 3339 có độ lệch múi giờ.

Phản hồi

200Phản hồi thành công

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: WebhookEventList

  • dataarray of WebhookEventbắt buộc
  • next_cursorstringbắt buộc

    Con trỏ cho yêu cầu tiếp theo. Nó luôn được trả về, kể cả khi has_more là false: hãy lưu nó và tiếp tục thăm dò từ cùng vị trí, sự kiện mới sẽ đến trong yêu cầu tiếp theo.

  • has_morebooleanbắt buộc

    Còn sự kiện sau trang này.

400Yêu cầu không hợp lệ: giá trị tham số hoặc trạng thái của đối tượng không cho phép thực hiện hành động (`detail` là thông báo).

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

401Không có thông tin xác thực nào được gửi (không có cookie phiên lẫn khóa API), hoặc không tìm thấy khóa.

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

403Hành động không được phép: vai trò không đủ quyền, không có quyền truy cập vào bộ sưu tập hoặc thẻ, yêu cầu chạy ở chế độ “View as”, hoặc tổ chức bị tạm ngưng hay đã bị xóa (`detail` là đối tượng có `code: org_suspended | org_deleted`).

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

422Lỗi dữ liệu không hợp lệ: phần thân hoặc tham số không khớp với lược đồ (`detail` là danh sách lỗi dữ liệu không hợp lệ), hoặc giá trị tham số nằm ngoài phạm vi cho phép (`detail` là thông báo).

Header phản hồi

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

429Quá nhiều yêu cầu (`api.rate_limited`), hạn mức của tổ chức theo phút, ngày hoặc tháng đã dùng hết (`api.quota_exceeded`; `error.details` chứa `quota`, `limit` và `reset_at`), tổ chức đã đạt giới hạn, hoặc dịch vụ trả lời đang bận (`answers.engine_busy`). Hãy chờ khoảng thời gian ghi trong header `Retry-After`.

Header phản hồi

  • Retry-After

    Số giây cần chờ trước khi thử lại yêu cầu.

  • RateLimit-Policy

    Các giới hạn đang áp dụng, theo định dạng của bản dự thảo IETF draft-ietf-httpapi-ratelimit-headers: các mục phân tách bằng dấu phẩy "<name>";q=<quota>;w=<window in seconds>. key là tốc độ yêu cầu của khóa API (hạn mức là đợt tăng đột biến, khung thời gian là thời gian để hạn mức hồi lại hoàn toàn; với phiên là user, khi không có thông tin xác thực là ip); minute, day và month là hạn mức của tổ chức cho phút, ngày và tháng theo lịch, tính theo UTC.

  • RateLimit

    Phần còn lại của mỗi giới hạn trong RateLimit-Policy: "<name>";r=<remaining>;t=<seconds until reset>.

  • X-RateLimit-Limit

    Giới hạn của mục chặt nhất trong RateLimit-Policy (mục còn ít yêu cầu nhất).

  • X-RateLimit-Remaining

    Số yêu cầu còn lại theo giới hạn chặt nhất.

  • X-RateLimit-Reset

    Số giây cho đến khi giới hạn chặt nhất được đặt lại.

application/json

Đối tượng: Error

Mã lỗi

Các mã endpoint này có thể trả về trong error.code, ngoài các mã chung của mọi yêu cầu.

Giới hạn tốc độ

Phản hồi có các header RateLimit và RateLimit-Policy cùng các header cũ hơn X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset. Phản hồi 429 có Retry-After tính bằng giây: hãy chờ rồi thử lại.

← webhooks · Tài liệu tham chiếu API