设置智能体事件的 Webhook

Webhook 会在发生特定情况（例如智能体任务完成或智能体等待审批）时，立即向你的端点发送一个已签名的 POST，因此你的系统无需进行轮询。本文介绍了如何添加端点、相关事件、有效载荷、验证签名以及投递失败时的处理方式。

开始之前#

• Webhook 适用于 Pro、Business 和 Custom 计划（“Webhook 适用于 Pro 及以上计划”）。
• 只有工作区所有者和管理员可以管理 Webhook。 其他成员会看到“只有所有者和管理员可以管理 Webhook”。
• 你需要一个公共的 https 地址，该地址需在 10 秒内返回 2xx 状态码。
• 每个工作区最多可以拥有 10 个 Webhook。

添加 Webhook#

1. 打开 Webhook 选项卡#

   打开工作区菜单，选择 AI agents & API，然后打开 Webhooks。点击 新 Webhook。

   

2. 输入端点#

   • 端点 URL：“一个公共 HTTPS 地址。”例如 https://example.com/clevera/webhooks。
   • 描述：可选，最多 200 个字符，例如“Slack 中继”。

3. 选择事件#

   勾选要接收的事件，或选择 所有事件，包括新事件。标记为 即将推出 的事件虽然可以被接受，但“目前还没有发送此事件的内容”。

   

4. 创建并保存密钥#

   点击 创建 Webhook。签名密钥（以 whsec_ 开头）仅显示一次：“立即复制：你将无法再次看到它。使用它来检查 Clevera-Signature 标头。”像保存密码一样保存它，然后点击 我已保存。

5. 发送测试事件#

   打开 Webhook 的 ⋯ 菜单并选择 发送测试事件。Clevera 会发送一次已签名的 ping 事件（不重试）。“测试事件已发送”表示它已离开 Clevera；请检查 投递 以查看你端点的响应。

事件#

以下事件被列为 即将推出 且尚未发送：job.progress、video.ready、article.ready、research.completed、insights.weekly。

任务事件涵盖智能体启动的任务（通过 API 令牌或已连接的应用），不包括用户在应用中启动的视频。

Clevera 发送的内容#

每次投递都是一个带有 JSON 正文和以下标头的 POST：

有效载荷携带 ID、链接、状态和数字，绝不包含内容本身。要读取已完成的视频或文章，请使用令牌调用 API。

{
  "id": "6f1c2d3e-4b5a-4c6d-8e9f-0a1b2c3d4e5f",
  "event": "job.succeeded",
  "created_at": "2026-10-20T14:03:11Z",
  "data": {
    "job": {
      "id": "job_8k2m4n6p8r0t2v4x",
      "kind": "video.create",
      "status": "succeeded",
      "error_code": null,
      "subject": { "type": "video", "id": "vid_example" },
      "credits_spent": 64
    },
    "needs_input": null,
    "workspace": { "id": "tm_example" }
  }
}

{
  "id": "0b9a8c7d-6e5f-4a3b-9c2d-1e0f9a8b7c6d",
  "event": "approval.requested",
  "created_at": "2026-10-20T14:01:02Z",
  "data": {
    "approval": {
      "id": "apr_example",
      "kind": "spend",
      "status": "pending",
      "credits_high": 80,
      "expires_at": "2026-10-21T14:01:02Z",
      "decided_at": null,
      "url": "https://app.clevera.ai/agents?tab=requests&team=tm_example"
    },
    "job": { "id": "job_8k2m4n6p8r0t2v4x", "kind": "video.create" },
    "workspace": { "id": "tm_example" }
  }
}

验证签名#

在信任每次投递之前请先进行检查。签名是 HMAC-SHA256，使用你的签名密钥对时间戳、一个点和原始请求正文进行加密：<t>.<body>。

1. 从 Clevera-Signature 标头中读取 t 和 v1。
2. 将 HMAC-SHA256(secret, t + "." + rawBody) 计算为十六进制。
3. 以恒定时间将其与 v1 进行比较。
4. 拒绝 t 超过 5 分钟的投递，以防止捕获的请求被重放。

import crypto from 'node:crypto';

export function verifyClevera(rawBody, header, secret, toleranceSeconds = 300) {
  const parts = Object.fromEntries(header.split(',').map((p) => p.trim().split('=')));
  const t = Number(parts.t);
  if (!parts.v1 || !Number.isInteger(t)) return false;
  if (Math.abs(Date.now() / 1000 - t) > toleranceSeconds) return false;
  const expected = crypto.createHmac('sha256', secret).update(`${t}.${rawBody}`).digest('hex');
  return expected.length === parts.v1.length &&
    crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}

import hashlib, hmac, time

def verify_clevera(raw_body: bytes, header: str, secret: str, tolerance: int = 300) -> bool:
    parts = dict(p.strip().split("=", 1) for p in header.split(","))
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not t.isdigit() or not v1 or abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), f"{t}.".encode() + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

function verifyClevera(string $rawBody, string $header, string $secret, int $tolerance = 300): bool
{
    parse_str(str_replace(',', '&', $header), $parts);
    $t = $parts['t'] ?? '';
    $v1 = $parts['v1'] ?? '';
    if (! ctype_digit($t) || $v1 === '' || abs(time() - (int) $t) > $tolerance) {
        return false;
    }
    return hash_equals(hash_hmac('sha256', $t.'.'.$rawBody, $secret), $v1);
}

请使用接收到的原始正文。先解析再重新编码 JSON 会改变字节，导致签名不匹配。

重试和失败#

当你的端点以 2xx 状态响应时，投递即视为成功。任何其他情况都会导致尝试失败：

• 任何其他状态，包括重定向（不跟随 3xx）；
• 10 秒内无响应（连接超时为 5 秒）；
• 地址无法再解析到公共互联网。

Clevera 会在 1 分钟、5 分钟、30 分钟、2 小时和 6 小时后重试失败的投递，共 5 次。你的端点响应正文不会被读取。

当连续 15 次投递尝试均失败时，Webhook 将被关闭：“已在连续 15 次投递失败后关闭。请修复端点，然后开启它。”所有者和管理员会收到“Webhook 到 host 已关闭”的通知：“其投递持续失败。请修复端点，然后重新开启它。”在关闭期间发生的事件不会被发送。测试事件不计入此限制。

管理 Webhook#

点击 Webhook 上的 投递 以查看其日志，或打开其 ⋯ 菜单以获取其他选项：

如果工作区不再使用 Pro 计划#

Webhook 仍会列出，也可以进行编辑和删除，但不会发送任何内容。等待重试的投递将以 plan_locked 失败，并且 发送测试事件 和 重新投递 会显示“Webhook 不在你的计划内。”升级回 Pro 计划后将恢复发送；没有任何内容会被删除。

故障排除#

相关内容#