Skip to main content
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.
Nếu bạn xoay lại trong khi cửa sổ ân hạn vẫn đang mở, secret vừa bị thay thế trở thành secret trước đây mới và một cửa sổ 24 giờ mới bắt đầu. Chỉ một secret trước đây được giữ tại một thời điểm.

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):
Trong cửa sổ 24 giờ sau khi xoay, header 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.
Mỗi giá trị trong 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ê.
Việc chấp nhận nếu bất kỳ chữ ký nào được liệt kê khớp chính là điều làm cho việc xoay không có downtime: một bên nhận vẫn được cấu hình với secret cũ sẽ khớp 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
Luôn tính HMAC trên các byte body request thô, chính xác như đã nhận — không phải trên một đối tượng JSON được tuần tự hóa lại. Việc tuần tự hóa lại có thể thay đổi khoảng trắng hoặc thứ tự khóa và làm hỏng việc xác thực. Sử dụng so sánh thời gian không đổi (chẳng hạn như crypto.timingSafeEqual) để tránh các cuộc tấn công timing.
Nếu bản ghi secret hiện tại của một lần gửi bị thiếu, lần gửi vẫn tiếp tục không được ký (không có header chữ ký) thay vì thất bại. Nếu chỉ bản ghi secret trước đây bị mất, chữ ký trước đây sẽ bị bỏ qua và chữ ký hiện tại vẫn được phát ra trong cả hai header.