什麼是 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 與相同的 payload。
傳遞語意與冪等性
Ayrshare 以**至少一次（at least once）**的方式傳遞 Webhook。偶爾出現的重複是正常運作，並非缺陷——每個接收端都需要將冪等性視為長期屬性。 重複會以兩種不同的形式出現，且各自需要不同的鍵：hookId 代表一次事件傳遞。同一次傳遞的每次重試都使用相同的 hookId，因此以它作為判定依據可以安全處理重試——但同一底層事件的新一次通知會帶著新的 hookId 送達，因此僅靠 hookId 無法辨識該情況。
建議的接收端流程：
- 先回應。 立即回傳
2xx，然後以非同步方式處理。逾時並不代表拒絕——若你完成了工作但太晚回應，該事件會再次被送出。 - 原子式地宣告
hookId——請求一到達時就立即進行，例如使用唯一約束、INSERT ... ON CONFLICT DO NOTHING，或SET NX——而非先讀後寫的檢查。兩次嘗試可能同時到達，先檢查後動作的做法會讓兩者都通過。 - 同時宣告一個由你自行建立的鍵，由 payload 組成，以便帶有新
hookId的第二次通知也能被辨識。對於messages，將id與subAction組合使用效果不錯。 - 然後才進行處理，並將兩個宣告保持足夠久，涵蓋重試視窗與後續可能的再次通知。
payload 中的
id 本身對每一種事件類型並非唯一——同一個 message id 會在編輯與回應中重複出現，而 messageRead 的 payload 並不帶 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）。