POST/v1/webhooks/{webhook_id}/rotate-secret

Xoay vòng khóa bí mật để ký

rotate_webhook_secret

Khóa bí mật mới chỉ hiển thị một lần. Khóa bí mật trước tiếp tục ký các lần gửi thêm overlap_hours giờ (mặc định 24, từ 0 đến 168). Trong thời gian đó, header X-KB-Signature chứa hai giá trị v1=, còn webhook-signature chứa hai giá trị v1,… phân tách bằng dấu cách: một cho khóa bí mật mới và một cho khóa bí mật trước. Để kết thúc sớm thời gian chồng lấn, hãy gọi POST /v1/webhooks/{webhook_id}/revoke-previous-secret.

Xác thực

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

Tham số đường dẫn

webhook_idintegerbắt buộc

Tham số header

Idempotency-Keystring
Khóa để thử lại an toàn một thao tác ghi: 1 đến 255 ký tự ASCII in được; nên dùng một UUID v4 cho mỗi thao tác logic. Lần thử lại với cùng khóa trong vòng 24 giờ không chạy lại thao tác: dịch vụ trả về phản hồi đã lưu (trạng thái, header và phần thân) kèm header Idempotency-Replayed: true. Cùng khóa nhưng khác phương thức, đường dẫn, Content-Type hoặc phần thân trả về 409 api.idempotency_mismatch; khi yêu cầu đầu tiên vẫn đang chạy, trả về 409 api.idempotency_in_progress kèm Retry-After: 1. Sau phản hồi 5xx hoặc 429, khóa được giải phóng và lần thử lại sẽ chạy lại thao tác. Khóa có phạm vi theo tổ chức và bên gọi (khóa API, người dùng hoặc khóa nguồn tùy chỉnh).
length ≥ 1, length ≤ 255

Phần thân yêu cầu

application/json

Đối tượng: WebhookRotateSecret

overlap_hoursinteger
Số giờ mà các lần gửi vẫn được ký thêm bằng khóa bí mật cũ.
Mặc định: 24≥ 0, ≤ 168

Phản hồi

200Khóa bí mật mới

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.
Idempotency-Replayed
true nghĩa là phản hồi được phát lại từ phản hồi đã lưu cho Idempotency-Key này: thao tác không chạy lại.

application/json

Đối tượng: WebhookSecret

secretstringbắt buộc
whsec_ theo sau là 32 byte ở dạng base64 (khóa bí mật mới dùng bảng chữ cái chuẩn có phần đệm, khóa cũ dùng base64url). Hãy lưu nó ở phía máy chủ nhận; nó không bao giờ xuất hiện lại trong phản hồi API. Khóa ký theo Standard Webhooks là kết quả giải mã base64 của phần sau whsec_.
previous_valid_untilstring (date-time) | null
Khóa bí mật cũ còn được chấp nhận đến thời điểm nào (sau khi xoay vòng). null khi tạo.

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

404Đối tượng không tồn tại hoặc bạn không có quyền truy cập. API không xác nhận sự tồn tại của đối tượng bị hạn chế quyền truy cập.

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.

Thử lại an toàn

Gửi header Idempotency-Key (ví dụ một UUID) với mỗi yêu cầu POST và PATCH. Một lần thử lại với cùng khóa trong vòng 24 giờ trả về phản hồi đã lưu thay vì thực hiện lạ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

curl -X POST 'https://api.sursa.com/v1/webhooks/1/rotate-secret' \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"overlap_hours":24}' \
  -H "Authorization: Bearer $SURSA_API_KEY"

Dùng thử

Khóa API

Khóa chỉ được giữ trong bộ nhớ của tab này và chỉ được gửi tới https://api.sursa.com.

Yêu cầu tác động lên dữ liệu thật của tổ chức bạn.

Idempotency-Key header

webhook_id path *

Idempotency-Key

Khi để trống, mỗi yêu cầu sẽ được tạo một khóa mới.

Phần thân yêu cầu (JSON)