Webhooks
輪替簽章密鑰
以 24 小時雙簽章寬限視窗安全輪替你的 Webhook 簽章密鑰
POST
概觀
Ayrshare 會以你的簽章密鑰為金鑰,使用 payload 的 HMAC-SHA256 對每一次 Webhook 傳遞進行簽章,讓你的接收端能確認該傳遞確實來自 Ayrshare。驗證方式請參閱 Webhook 安全性。 輪替簽章密鑰讓你可以按固定排程更換密鑰,或在懷疑密鑰外洩時立即更換。為了讓輪替安全進行,Ayrshare 會在每次輪替後開啟一個 24 小時寬限視窗,這段期間內的傳遞會同時使用你的舊密鑰與新密鑰簽章。這讓你可以依自己的節奏更新接收端,且不會丟失或拒絕任何一次傳遞——這與 Stripe 和 GitHub 使用的模式相同。簽章密鑰為 profile 層級:每個 User Profile(UID)只有一個密鑰,
該密鑰會為該 profile 註冊的每一個 Webhook 動作簽章。並沒有
per-action 的簽章密鑰——設定或輪替密鑰時,會同時變更該 profile 上
所有動作的密鑰。
從控制台輪替
你可以在開發者控制台的 Webhooks 頁面 設定或輪替簽章密鑰。當該 profile 至少註冊一個 Webhook 時,Signing Secret 面板會出現在 Webhook 清單上方。1
開啟 Signing Secret 面板
前往 Webhooks 頁面。若尚未設定密鑰,面板會顯示 No signing secret configured 及 Set Signing Secret 按鈕。若已設定密鑰,則會顯示 Signing secret configured 及 Rotate 按鈕。
2
設定或輪替
點擊 Set Signing Secret(首次設定)或 Rotate(既有密鑰)。會開啟一個 modal,其中已預先填入並顯示一組強隨機產生的密鑰。你可以 Copy 密鑰、Regenerate 產生新的一組,或切換 paste my own 以提供自己的值。
3
確認
將密鑰複製並妥善保存——它只會顯示一次,之後無法再從 UI 取得——接著確認送出。會出現成功提示,面板也會更新。
4
更新你的接收端
在輪替(而非首次設定)時,面板會顯示啟用中的寬限視窗指示器,且 Rotate 按鈕在視窗關閉前會被停用。你有 24 小時的時間將新密鑰部署到接收端。
透過 API 輪替
只需一次呼叫即可輪替(或設定)簽章密鑰。這會建立一組新密鑰、將該 profile 的密鑰參照指向該新密鑰,並在原本已存在密鑰的情況下,將被取代的密鑰記錄為 previous secret,並設定 24 小時後到期。標頭參數
Body 參數
string
必填
新的簽章密鑰值。任何非空字串皆可接受。建議使用高熵、較長的隨機值(例如以 base64url 編碼的 32 個隨機位元組)。
secret 絕不會於回應中回傳,也不會被記錄。回應會攜帶對外的 refId(UID 的 hash),絕不會攜帶 UID 本身。Profile-Key 標頭為選用,用於在多 profile 帳號中將輪替限縮至單一 User Profile。
若 secret 缺少或為空,會回傳對應的錯誤(code: 101,“Missing/incorrect parameter”)並帶有 HTTP 400 狀態,且不會變更你目前的密鑰。透過 API 首次設定(無既有密鑰)會建立密鑰,且不會記錄 previous secret 也不會啟動寬限視窗。
安全輪替流程
由於有 24 小時寬限視窗,並沒有必要的操作先後順序——你的接收端在整個過程中都能正常運作。建議的順序如下:1
輪替密鑰
從控制台或透過 API 輪替。Ayrshare 會立即開始同時使用舊密鑰與新密鑰為傳遞簽章。
2
更新你的接收端
在 24 小時內,將新密鑰部署到你的 Webhook 接收端,讓它以新密鑰進行驗證。
3
讓視窗自然關閉
24 小時後,Ayrshare 會自動清除舊密鑰並只以新密鑰簽章。你這一端不需要再做任何動作。
在寬限視窗期間驗證簽章
在寬限視窗以外,已簽章的傳遞會攜帶標準標頭(請參閱 Webhook 安全性):X-Authorization-Content-SHA256-V2 標頭會列出兩組簽章,以 current 在前、逗號分隔的形式呈現:
X-Authorization-Content-SHA256 沒有變化:它一律只攜帶單一
以 current secret 計算的 HMAC,以維持向下相容。雙簽章只會出現在
新的 X-Authorization-Content-SHA256-V2 標頭中。X-Authorization-Content-SHA256-V2 中的每個值都會以 scheme 標籤作為前綴。v1= 表示 HMAC-SHA256 簽章,計算方式與 X-Authorization-Content-SHA256 完全相同。只要傳遞有簽章,-V2 標頭就一定會出現——至少會攜帶 v1=<current-sig>——因此你可以將它視為穩定的接收端契約來依賴。
要在輪替期間(或平時)驗證一次傳遞:
1
計算 HMAC
使用你接收端本地設定的簽章密鑰,對原始請求主體計算 HMAC-SHA256。
2
與每個列出的簽章比對
讀取
X-Authorization-Content-SHA256-V2,以逗號分割,將每個值去除 v1= 前綴,若你計算出的 HMAC 與任一列出的 v1= 簽章相符,就視為傳遞為真。v1=<previous-sig>,已更新為新密鑰的接收端則會匹配到 v1=<current-sig>——在整個視窗期間兩者都能通過。
接收端驗證範例
Node.js
