什麼是 Webhook？
Webhook 讓你可以在系統發生特定「動作（action）」時，透過對你提供的 URL 發起呼叫來收到通知。Webhook 也稱為「URL 回呼」或「HTTP push 呼叫」。你提供的 URL 必須使用 SSL，並以 HTTPS 開頭。Webhook 動作
查看可用的 Webhook 動作。
認識 Ayrshare Webhook
Webhook 依據特定動作進行分類，並註冊於 Primary Profile 或 User Profile 層級。任何 Primary 或 User Profile 的更新都會先送到該 User Profile 已註冊的 Webhook。若該 User Profile 未註冊 Webhook，則更新會送到 Primary Profile 註冊的 Webhook。 例如：- 若某 User Profile 已註冊 Social Action Webhook 並解除 TikTok 的連結，該 User Profile 註冊的 Social Action Webhook URL 會被呼叫。Primary Profile 的 Webhook 不會被呼叫。
- 若某 User Profile 解除 TikTok 連結且未註冊 Social Action Webhook，但 Primary Profile 有註冊 Webhook，則會呼叫 Primary Profile 註冊的 Social Action Webhook URL。
註冊 Webhook
透過將端點 URL 與動作類型提交至 POST/hook/webhook 端點來註冊 Webhook。當該動作發生時，會向你提供的 URL 送出 HTTP POST 訊息。
例如：註冊一個 URL，以便在排程貼文狀態變化時收到通知。
Webhook 端點 URL 不應使用轉址，必須是最終目的地的 URL。
若你只註冊 Primary Profile 的 Webhook，User Profile 會自動繼承 Primary Profile 的 Webhook。
若要為每個 User Profile 設定不同的 Webhook，你必須為每個 User Profile 各別註冊 Webhook。
在你的 Webhook 收到
HTTP POST 之後，你的伺服器必須回應 HTTP 狀態 200，才會將該次呼叫標記為成功。若你的伺服器在 15 秒內未回應，該次嘗試會被記錄為失敗並進行重試。請在收到請求後立即回應，並以非同步方式進行後續處理——逾時並不等於拒絕，因此若你的處理程序完成了工作卻回應太慢，重試會導致你重複處理同一事件。Webhook 重試
若你的伺服器回應的 HTTP 狀態不在200-299 成功範圍內，或你的伺服器在 15 秒內未回應，系統會自動再重試 Webhook 呼叫兩次。第一次重試在 5 秒後進行，第二次重試在 30 秒後進行。重試會使用相同的 hookId 與相同的酬載內容。
傳遞語意與冪等性
Ayrshare 的 Webhook 採用至少一次（at least once） 傳遞。偶發的重複屬於正常運作，並非缺陷——每個接收端都必須將冪等性視為永久性的特性。 重複會以兩種不同型態出現，各自需要不同的鍵值來辨識：hookId 代表事件的單一次傳遞。同一次傳遞的每次重試上都相同，因此以 hookId 進行認領可以安全處理重試——但同一底層事件的新一次通知會帶有新的 hookId，所以單靠 hookId 無法辨識這種情況。
建議的接收端模式：
- 先回應。 立刻回傳
2xx，再以非同步方式處理。逾時並不等於拒絕——若你完成了工作卻回應太慢，該事件會被再次送出。 - 以原子方式認領
hookId，在請求一到達時就完成——例如唯一鍵約束、INSERT ... ON CONFLICT DO NOTHING、或SET NX——不要使用先讀後寫的檢查。兩次嘗試可能同時到達，「檢查後行動」的保護方式會讓兩次都通過。 - 同時也要認領你自己組建的鍵，從酬載中衍生而來，這樣即使第二次通知帶著新的
hookId，也仍能被辨識出來。對messages而言，將id與subAction組合起來效果不錯。 - 然後再執行實際工作，並將兩個認領持有到足以涵蓋重試視窗以及後續可能發生的再次通知為止。
酬載中的
id 對每種事件類型而言並非唯一——同一個 message id 會在編輯與回應中重複出現，而 messageRead 的酬載並不帶 id——因此請將它與 subAction 組合使用，而非單獨使用。傳遞元資料標頭
每一次傳遞都會附帶兩個標頭以標示該次特定傳輸，讓你能區分原始傳遞與重試：X-Ayrshare-Delivery-Attempt 在首次送出時為 0，之後每次重試遞增 1，因此任何大於 0 的值都代表我們已經至少傳送過這次傳遞一次。請將其視為無上限的計數器，而非固定的一組值——重試次數屬於可能會變動的營運細節。X-Ayrshare-Delivery-Id 對每次嘗試皆為唯一——向支援團隊回報時附上此值，即可精確定位該筆傳遞紀錄。
這些標頭標識的是傳輸；hookId 標識的則是事件。請以 hookId 進行去重，而非以 delivery id——delivery id 依設計就會在每次嘗試時不同，若以此去重將無法辨識出任何重複。
Webhook 安全性
你可以選擇加入額外的安全性，將 HMAC 驗證設為 HTTP 請求的一部分。這通常用於防止重放攻擊。Ayrshare 使用 HMAC-SHA256 對訊息主體進行雜湊處理，並將雜湊值與 UNIX 時間戳一起放在 POST 的標頭中。X-Authorization-Content-SHA256 與 POST body 的 HMAC-SHA256 來驗證此貼文。簽章密鑰為 profile 層級——每個 User Profile 只有一組密鑰，並會套用於該 profile 所有 Webhook 動作，因此為某個動作設定密鑰時，該 profile 上所有動作的密鑰皆會一併變更。多 profile 帳號會為每個 profile 各自管理獨立的密鑰（透過 Profile-Key 標頭指定 profile）。