Skip to main content
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 會自動清除前一版密鑰,並僅以新密鑰簽章。你這邊不需要再做任何動作。
如果在寬限期尚未結束時再次輪替,剛才被取代的密鑰會成為新的前一版密鑰,並重新開始一段 24 小時的寬限期。任何時候只會保留一份前一版密鑰。

於寬限期內驗證簽章

在寬限期以外,帶簽章的傳遞內容會帶有標準標頭(請參閱 Webhook 安全性):
在輪替後的 24 小時寬限期內,新的 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
請一律針對原始的 request body 位元組(收到什麼就用什麼)計算 HMAC——不要對重新序列化過的 JSON 物件計算。重新序列化可能會改變空白或鍵值順序,導致驗證失敗。請使用常數時間比較(例如 crypto.timingSafeEqual)以避免時序攻擊。
若某次傳遞的目前密鑰紀錄遺失,該次傳遞會以未簽章(沒有簽章標頭)的形式送出,而不是失敗。若只有前一版密鑰的紀錄遺失,則會略過前一版簽章,仍然會在兩個標頭中送出目前的簽章。