Webhooks
輪替簽署密鑰
透過 24 小時的雙重簽署寬限期,安全地輪替你的 Webhook 簽署密鑰
POST
概觀
Ayrshare 會使用以你的簽署密鑰為金鑰的 HMAC-SHA256 為每一次 Webhook 傳遞的內容簽章,讓你的接收端可以確認該傳遞確實來自 Ayrshare。驗證的運作方式請參閱 Webhook 安全性。 輪替簽署密鑰可讓你依固定週期更換密鑰,或在懷疑密鑰已外洩時立即更換。為了讓輪替過程安全無虞,Ayrshare 會在每次輪替後開啟一段 24 小時的寬限期,在此期間傳遞的內容會同時以你的舊密鑰與新密鑰簽章。這讓你可以依自己的節奏更新接收端,而不會漏掉或拒絕任何一次傳遞——這與 Stripe 與 GitHub 採用的模式相同。簽署密鑰是整個 profile 範圍的:每個 User Profile(UID)只有一個密鑰,且該密鑰會為該 profile 已註冊的每一個 Webhook 動作簽章。並沒有針對個別動作的簽署密鑰——設定或輪替密鑰時,該 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 的密鑰參照重新指向新密鑰,並且——當先前已有密鑰存在時——將被取代的密鑰記錄為前一版密鑰,並設定 24 小時後到期。標頭參數
Body 參數
string
必填
新的簽署密鑰值。可接受任何非空字串。我們建議使用長度足夠、熵值高的隨機值(例如以 base64url 編碼的 32 位元隨機位元組)。
secret 絕不會在回應中回傳,也永不會被寫入日誌。回應會帶入面向用戶端的 refId(UID 的雜湊值),永遠不會是 UID 本身。Profile-Key 標頭為選用,對多 profile 帳號可將此輪替範圍限定於單一 User Profile。
若缺少或提供空的 secret,會回傳對應的錯誤(code: 101,「Missing/incorrect parameter」)及 HTTP 400 狀態,且不會變更你目前的密鑰。透過 API 首次設定密鑰(尚無既有密鑰)時,會建立密鑰但不記錄前一版密鑰,也不會有寬限期。
安全輪替流程
由於有 24 小時的寬限期,並沒有一定要遵循的操作順序——過程中你的接收端會持續正常運作。建議的順序如下:1
輪替密鑰
從控制台或透過 API 輪替。Ayrshare 會立即開始同時以你的舊密鑰與新密鑰為傳遞內容簽章。
2
更新你的接收端
在 24 小時內,將新密鑰部署到你的 Webhook 接收端,讓它以新值進行驗證。
3
讓寬限期結束
24 小時之後,Ayrshare 會自動清除前一版密鑰,並僅以新密鑰簽章。你這邊不需要再做任何動作。
於寬限期內驗證簽章
在寬限期以外,帶簽章的傳遞內容會帶有標準標頭(請參閱 Webhook 安全性):X-Authorization-Content-SHA256-V2 標頭會列出兩組簽章,目前的簽章在前,以逗號分隔:
X-Authorization-Content-SHA256 維持不變:為了向下相容,它一律只帶目前密鑰的單一 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
使用你本機設定的簽署密鑰,計算原始 request body 的 HMAC-SHA256。
2
與所有列出的簽章比對
讀取
X-Authorization-Content-SHA256-V2、以逗號分隔切開、去除每個值的 v1= 前綴,只要你計算得到的 HMAC 與任一個列出的 v1= 簽章相符,就接受該傳遞為真實可信。v1=<previous-sig>,而已更新為新密鑰的接收端會比對到 v1=<current-sig>——在整段寬限期中兩者都能成功。
接收端驗證範例
Node.js
