curl --request POST \
--url https://api.ayrshare.com/api/hook/webhook/secret \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Profile-Key: YOUR_PROFILE_KEY' \
--data '{
"secret": "your-new-signing-secret"
}'
{
"status": "success",
"action": "webhook",
"refId": "3dc079614bdc3f281d9" // User Profile Ref Id
}
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
/
hook
/
webhook
/
secret
curl --request POST \
--url https://api.ayrshare.com/api/hook/webhook/secret \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Profile-Key: YOUR_PROFILE_KEY' \
--data '{
"secret": "your-new-signing-secret"
}'
{
"status": "success",
"action": "webhook",
"refId": "3dc079614bdc3f281d9" // User Profile Ref Id
}
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).
curl --request POST \
--url https://api.ayrshare.com/api/hook/webhook/secret \
--header 'Authorization: Bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--header 'Profile-Key: YOUR_PROFILE_KEY' \
--data '{
"secret": "your-new-signing-secret"
}'
{
"status": "success",
"action": "webhook",
"refId": "3dc079614bdc3f281d9" // User Profile Ref Id
}
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):X-Authorization-Timestamp : <Unix Timestamp In Seconds>
X-Authorization-Content-SHA256 : <current-sig>
X-Authorization-Content-SHA256-V2 : v1=<current-sig>
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-Timestamp : <Unix Timestamp In Seconds>
X-Authorization-Content-SHA256 : <current-sig>
X-Authorization-Content-SHA256-V2 : v1=<current-sig>,v1=<previous-sig>
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
import crypto from "crypto";
// secret is the signing secret currently configured on your receiver.
function isAuthenticWebhook(rawBody, headers, secret) {
const expected = crypto
.createHmac("sha256", secret)
.update(rawBody) // the raw, unparsed request body
.digest("hex");
const headerValue = headers["x-authorization-content-sha256-v2"] || "";
// Accept if ANY v1= signature in the header matches our computed HMAC.
return headerValue
.split(",")
.map((part) => part.trim())
.filter((part) => part.startsWith("v1="))
.map((part) => part.slice("v1=".length))
.some((sig) => {
const sigBuf = Buffer.from(sig);
const expectedBuf = Buffer.from(expected);
// timingSafeEqual throws on length mismatch — treat as not authentic.
return (
sigBuf.length === expectedBuf.length &&
crypto.timingSafeEqual(sigBuf, expectedBuf)
);
});
}
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.