> ## 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.

# Webhook 概览

> 用于注册 webhook 以接收事件更新的 Webhook API 端点

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 Actions" icon="link" href="/apis/webhooks/actions" horizontal>
  查看 webhook 可用的 action。
</Card>

### 理解 Ayrshare 的 Webhook

Webhook 按具体的 action 分类,且 *在 Primary Profile 或 User Profile 层面进行注册*。Primary Profile 或 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

通过向 POST [`/hook/webhook`](/apis/webhooks/register) 端点提供一个端点 URL 及 action 类型来注册 Webhook。当该 action 发生时,系统会向所提供的 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) 对消息 body 进行哈希,并将其与 UNIX 时间戳一起放入 POST 的 header 中。

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

基于你在[注册 webhook](/apis/webhooks/register) 时设置的密钥 (secret key),你可以将 header 中的 X-Authorization-Content-SHA256 与 POST body 的 SHA256 哈希值进行比较来验证请求。该密钥在所有 webhook action 中通用,因此为某个 action 设置它就等于修改了所有 action 的密钥。

## 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 日志。

### 错误率

最近 1,000 条帖子的 "Error Rate" 可在控制台的 Actions 和 Webhook Logs 页面查看。任何来自你服务器的 400-500 webhook 响应都会被视为错误。