> ## Documentation Index
> Fetch the complete documentation index at: https://www.ayrshare.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks 概觀

> Webhook API 端點，用於註冊 Webhook 以接收事件更新

export const PlansAvailable = ({plans = [], maxPackRequired}) => {
  let displayPlans = plans;
  if (plans && plans.length === 1) {
    const lowerCasePlan = plans[0].toLowerCase();
    if (lowerCasePlan === "business") {
      displayPlans = ["Launch", "Business", "Enterprise"];
    } else if (lowerCasePlan === "premium") {
      displayPlans = ["Premium", "Launch", "Business", "Enterprise"];
    }
  }
  return <Note>
Available on {displayPlans.length === 1 ? "the " : ""}
{displayPlans.join(", ").replace(/\b\w/g, l => l.toUpperCase())}{" "}
{displayPlans.length > 1 ? "plans" : "plan"}.

{maxPackRequired && <span onClick={() => window.open('https://www.ayrshare.com/docs/additional/maxpack', '_self')} className="flex items-center mt-2 cursor-pointer">
 <span className="px-1.5 py-0.5 rounded text-sm" style={{
    backgroundColor: '#C264B6',
    color: 'white',
    fontSize: '12px'
  }}>
   Max Pack required
 </span>
</span>}
</Note>;
};

<PlansAvailable plans={["premium"]} maxPackRequired={false} />

## 什麼是 Webhook？

Webhook 讓你可以在系統發生特定「動作（action）」時，透過對你提供的 URL 發起呼叫來收到通知。Webhook 也稱為「URL 回呼」或「HTTP push 呼叫」。你提供的 URL 必須使用 SSL，並以 HTTPS 開頭。

<Card title="Webhook 動作" icon="link" href="/apis/webhooks/actions" horizontal>
  查看可用的 Webhook 動作。
</Card>

### 認識 Ayrshare Webhook

Webhook 依據特定動作進行分類，並**註冊於 Primary Profile 或 User Profile 層級**。任何 Primary 或 User Profile 的更新都會先送到該 User Profile 已註冊的 Webhook。若該 User Profile 未註冊 Webhook，則更新會送到 Primary Profile 註冊的 Webhook。

例如：

<ul class="custom-bullets">
  <li>
    若某 User Profile 已註冊 Social Action Webhook 並解除 TikTok 的連結，該 User Profile 註冊的 Social Action Webhook URL 會被呼叫。Primary Profile 的 Webhook **不會**被呼叫。
  </li>

  <li>
    若某 User Profile 解除 TikTok 連結且**未**註冊 Social Action Webhook，但 Primary Profile 有註冊 Webhook，則會呼叫 Primary Profile 註冊的 Social Action Webhook URL。
  </li>
</ul>

### 註冊 Webhook

透過將端點 URL 與動作類型提交至 POST [`/hook/webhook`](/apis/webhooks/register) 端點來註冊 Webhook。當該動作發生時，會向你提供的 URL 送出 `HTTP POST` 訊息。
例如：註冊一個 URL，以便在排程貼文狀態變化時收到通知。

Webhook 端點 URL 不應使用轉址，必須是最終目的地的 URL。

若你只註冊 Primary Profile 的 Webhook，User Profile 會自動繼承 Primary Profile 的 Webhook。
若要為每個 User Profile 設定不同的 Webhook，你必須為每個 User Profile 各別註冊 Webhook。

<Note>
  在你的 Webhook 收到 `HTTP POST` 之後，你的伺服器**必須**回應 HTTP 狀態 `200`，才算成功。若你的伺服器在 10 秒內未回應，將被記錄為 `503` 回應。
</Note>

你也可以在開發者控制台中註冊 Webhook。

### Webhook 重試

若你的伺服器回應 HTTP 狀態不在 `200-299` 成功範圍內，系統會自動重試 Webhook 呼叫兩次。第一次重試在 5 秒後進行，第二次重試在 30 秒後進行。重試會使用相同的 `hookId`，並被標記為重試。

## Webhook 安全性

你可以選擇加入額外的安全性，將 HMAC 驗證設為 HTTP 請求的一部分。這通常用於防止重放攻擊。Ayrshare 使用 [HMAC-SHA256](https://en.wikipedia.org/wiki/HMAC) 對訊息主體進行雜湊處理，並將雜湊值與 UNIX 時間戳一起放在 POST 的標頭中。

```bash theme={"system"}
X-Authorization-Timestamp : <Unix Timestamp In Seconds>
X-Authorization-Content-SHA256 : <HashedContent>
```

根據你[註冊 Webhook](/apis/webhooks/register) 時設定的密鑰，你可以透過比較標頭 X-Authorization-Content-SHA256 與 POST body 的 SHA256 雜湊值來驗證此貼文。此密鑰會套用於所有 Webhook 動作，因此為一個動作設定密鑰時，所有動作的密鑰皆會一併變更。

## Webhook 記錄

在 Ayrshare 控制台中，你可以查看[有效的 Webhook](https://app.ayrshare.com/webhooks)、查看已送出 Webhook 的詳細內容、你的伺服器回應狀態，並可將 Webhook 重新送至已註冊的 URL。
切換到特定 User Profile 即可查看該 Profile 的 Webhook 記錄。

### HTTP 回應碼

第一欄會標示 Webhook 是否為成功的 HTTP 回應 ✔️（200、300）或失敗回應 ✖️（400、500）。

切換到特定 User Profile 即可查看該 Profile 的 Webhook 記錄。

### 錯誤率

在控制台的 Actions 與 Webhook Logs 頁面上，可以查看最近 1,000 則貼文的「錯誤率（Error Rate）」。任何來自你的伺服器且回應為 400-500 的 Webhook 都會被視為錯誤。