Webhooks
Xoay Signing Secret
Xoay signing secret webhook của bạn một cách an toàn với cửa sổ ân hạn ký kép 24 giờ
POST
Tổng quan
Ayrshare ký mọi lần gửi webhook bằng HMAC-SHA256 của payload, sử dụng signing secret của bạn làm khóa, để bên nhận của bạn có thể xác nhận rằng lần gửi thực sự đến từ Ayrshare. Xem Bảo mật Webhook để biết cách xác thực hoạt động. Việc xoay signing secret cho phép bạn thay thế nó theo lịch trình định kỳ, hoặc ngay lập tức nếu bạn nghi ngờ nó đã bị lộ. Để việc xoay được an toàn, Ayrshare mở một cửa sổ ân hạn 24 giờ sau mỗi lần xoay, trong đó các lần gửi được ký bằng cả secret trước đây và secret mới của bạn. Điều này cho phép bạn cập nhật bên nhận theo lịch trình của riêng mình mà không bị rớt hay từ chối bất kỳ lần gửi nào — cùng một mẫu hình được sử dụng bởi Stripe và GitHub.Signing secret là phạm vi profile: có một secret duy nhất cho mỗi User Profile (UID),
và nó ký mọi webhook action mà profile đó đã đăng ký. Không có
signing secret riêng cho từng action — việc đặt hoặc xoay secret sẽ thay đổi nó cho tất cả
các action trên profile đó cùng một lúc.
Xoay từ Dashboard
Bạn có thể đặt hoặc xoay signing secret của mình từ trang Webhooks trong Developer Dashboard. Bảng Signing Secret xuất hiện phía trên danh sách webhook của bạn khi profile đã có ít nhất một webhook đăng ký.1
Mở bảng Signing Secret
Đi đến trang Webhooks. Nếu chưa có secret nào được cấu hình, bảng sẽ hiển thị No signing secret configured với nút Set Signing Secret. Nếu đã có một secret được cấu hình, bảng sẽ hiển thị Signing secret configured với nút Rotate.
2
Đặt hoặc Xoay
Nhấp Set Signing Secret (lần đầu) hoặc Rotate (secret hiện có). Một modal sẽ mở ra với một secret ngẫu nhiên mạnh được tạo sẵn và hiển thị. Bạn có thể Copy nó, Regenerate một cái mới, hoặc bật paste my own để cung cấp giá trị của riêng bạn.
3
Xác nhận
Sao chép secret vào một nơi an toàn — nó chỉ được hiển thị một lần và không bao giờ có thể truy xuất từ UI nữa — sau đó xác nhận để gửi. Một toast thành công sẽ xuất hiện và bảng sẽ cập nhật.
4
Cập nhật bên nhận của bạn
Khi xoay (không phải đặt lần đầu), bảng sẽ hiển thị chỉ báo cửa sổ ân hạn đang hoạt động và nút Rotate bị vô hiệu hóa cho đến khi cửa sổ đóng lại. Bạn có 24 giờ để triển khai secret mới đến bên nhận của mình.
Xoay qua API
Xoay (hoặc đặt) signing secret bằng một lệnh gọi duy nhất. Lệnh này tạo một secret mới, trỏ tham chiếu secret của profile đến nó, và — khi đã có một secret hiện có — ghi lại secret bị thay thế làm secret trước đây với thời hạn hết 24 giờ.Tham số Header
Tham số Body
string
bắt buộc
Giá trị signing secret mới. Bất kỳ chuỗi không rỗng nào cũng được chấp nhận. Chúng tôi khuyến nghị một giá trị ngẫu nhiên dài, có entropy cao (ví dụ: 32 byte ngẫu nhiên mã hóa dưới dạng base64url).
secret dạng plaintext không bao giờ được trả về trong phản hồi và không bao giờ được ghi log. Phản hồi mang refId hướng đến client (một hash của UID), không bao giờ là chính UID. Header Profile-Key là tùy chọn và giới hạn phạm vi xoay cho một User Profile duy nhất cho các tài khoản đa profile.
Một secret thiếu hoặc rỗng sẽ trả về lỗi được ánh xạ (code: 101, “Missing/incorrect parameter”) với trạng thái HTTP 400, và không thay đổi nào được thực hiện đối với secret hiện tại của bạn. Việc đặt lần đầu qua API (không có secret hiện có) tạo secret mà không có secret trước đây nào được ghi lại và không có cửa sổ ân hạn.
Quy trình Xoay An toàn
Nhờ cửa sổ ân hạn 24 giờ, không có thứ tự thao tác bắt buộc nào — bên nhận của bạn vẫn tiếp tục hoạt động trong suốt quá trình. Chuỗi thao tác được khuyến nghị là:1
Xoay secret
Xoay từ dashboard hoặc qua API. Ayrshare ngay lập tức bắt đầu ký các lần gửi bằng cả secret trước đây và secret mới của bạn.
2
Cập nhật bên nhận của bạn
Trong vòng 24 giờ, triển khai secret mới đến bên nhận webhook của bạn để nó xác thực dựa trên giá trị mới.
3
Để cửa sổ đóng lại
Sau 24 giờ, Ayrshare tự động xóa secret trước đây và chỉ ký bằng secret mới. Không cần thao tác thêm nào từ phía bạn.
Xác thực Chữ ký Trong Cửa sổ Ân hạn
Bên ngoài cửa sổ ân hạn, các lần gửi đã ký mang các header tiêu chuẩn (xem Bảo mật Webhook):X-Authorization-Content-SHA256-V2 mới liệt kê cả hai chữ ký, hiện tại trước, phân tách bằng dấu phẩy:
X-Authorization-Content-SHA256 không thay đổi: nó luôn mang HMAC của
secret hiện tại duy nhất, để tương thích ngược. Chữ ký kép chỉ xuất hiện trong
header X-Authorization-Content-SHA256-V2 mới.X-Authorization-Content-SHA256-V2 được tiền tố bằng một scheme tag. v1= biểu thị chữ ký HMAC-SHA256, được tính chính xác giống như X-Authorization-Content-SHA256. Header -V2 luôn hiện diện mỗi khi một lần gửi được ký — nó mang ít nhất v1=<current-sig> — vì vậy bạn có thể dựa vào nó như một hợp đồng bên nhận ổn định.
Để xác thực một lần gửi trong (hoặc ngoài) một lần xoay:
1
Tính HMAC
Tính HMAC-SHA256 của body request thô bằng signing secret được cấu hình cục bộ của bạn.
2
So sánh với mọi chữ ký được liệt kê
Đọc
X-Authorization-Content-SHA256-V2, tách nó theo dấu phẩy, loại bỏ tiền tố v1= khỏi mỗi giá trị, và chấp nhận lần gửi là hợp lệ nếu HMAC bạn tính khớp với bất kỳ chữ ký v1= nào được liệt kê.v1=<previous-sig>, trong khi một bên nhận đã cập nhật lên secret mới sẽ khớp v1=<current-sig> — cả hai đều thành công trong suốt cửa sổ.
Ví dụ Xác thực Bên nhận
Node.js
