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

# Webhook 与 Hook 事件

> 通过 Webhook 与 Hook 接收实时通知，并触发自主技能执行。

针对技能构建器 Input 节点的 **Webhook Event** 与 **Hook Event** 两种触发类型，Theo 提供两套互补的事件系统。

## Webhook —— 出站 HTTP 通知

Webhook 会将事件投递到你的 HTTP 端点。当 Theo 中发生某些事情（如生成完成、任务结束、技能安装等）时，系统会向每个匹配的端点发送一个带签名的 POST 请求。

### 注册 Webhook

<CodeGroup>
  ```bash curl theme={null}
  curl -X POST https://www.hitheo.ai/api/v1/webhooks \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://your-server.com/webhooks/theo",
      "event_types": ["completion.created", "job.completed"]
    }'
  ```

  ```typescript SDK theme={null}
  const webhook = await theo.createWebhook({
    url: "https://your-server.com/webhooks/theo",
    event_types: ["completion.created", "job.completed"],
  });
  // Save webhook.signing_secret — shown once only
  ```
</CodeGroup>

响应中包含一个 `signing_secret`——请妥善保存。它只会显示一次，用于验证载荷。

### 事件目录

| 事件 | 说明 |
| - | - |
| `completion.created` | 生成了一次补全（completion） |
| `job.completed` / `job.failed` | 后台任务已完成 |
| `workflow.completed` / `workflow.failed` | 工作流运行已完成 |
| `skill.installed` / `skill.uninstalled` | 技能安装/卸载 |
| `skill.submitted` / `skill.approved` / `skill.rejected` | 技能审核 |
| `connector.created` / `connector.status_changed` | 连接器事件 |
| `credits.low` | 额度余额不足 |
| `key.created` / `key.revoked` | API 密钥事件 |

使用 `"*"` 作为事件类型可接收所有事件。

### 验证签名

每次投递都包含 HMAC-SHA256 签名：

```
Theo-Webhook-Signature: v1=<hex>
Theo-Webhook-Timestamp: <unix_seconds>
Theo-Webhook-Id: <event_id>
```

通过计算 `HMAC-SHA256(signing_secret, timestamp + "." + raw_body)` 并进行比对来验证。如果时间戳偏差超过 5 分钟，应予以拒绝。

### 重试行为

* 对瞬时失败会以指数退避方式自动重试
* 服务端会对每次尝试强制执行超时限制
* 4xx 错误不会被重试（客户端错误）
* 持续投递失败一段时间后，Webhook 会被自动禁用
* 无论成功还是失败，每次尝试都会记录在投递日志中

### 管理 Webhook

* `GET /api/v1/webhooks` —— 列出所有 Webhook
* `PATCH /api/v1/webhooks/{id}` —— 更新 URL、事件类型、启用/禁用
* `DELETE /api/v1/webhooks/{id}` —— 删除
* `POST /api/v1/webhooks/{id}/test` —— 发送测试事件
* `GET /api/v1/webhooks/{id}/deliveries` —— 查看投递日志

***

## Hook 事件 —— 自主技能触发器

Hook 是内部事件触发器，在事件发生时自动执行技能——无需 HTTP 端点。技能会在带有额度护栏的自主执行器中以无头（headless）方式运行。

### Hook 的工作方式

1. 发布一个事件（通过 `POST /api/v1/events` 或内部平台事件）
2. Hook 评估器检查所有已启用的 Hook 是否存在模式匹配
3. 匹配到的 Hook 会加载对应的技能并自主执行
4. 结果会记录在执行日志中

### Hook 预设

| 预设 | 事件模式 | 默认技能 | 说明 |
| - | - | - | - |
| `share.accepted.welcome` | `share.accepted` | `email-drafter` | 分享被接受时发送欢迎消息 |
| `task.overdue.summary` | `task.overdue` | `todo-manager` | 汇总已逾期的任务 |
| `project.created.suggestions` | `project.created` | `document-analyzer` | 建议项目的后续步骤 |
| `team.member_joined.onboarding` | `team.member_joined` | `email-drafter` | 提供入职引导 |
| `document.analyzed.followup` | `document.analyzed` | `document-analyzer` | 生成后续行动项 |

### 安装 Hook

<CodeGroup>
  ```bash curl theme={null}
  # Using a preset
  curl -X POST https://www.hitheo.ai/api/v1/hooks \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "hook_preset_id": "share.accepted.welcome",
      "skill_slug": "email-drafter"
    }'

  # Using a custom event pattern
  curl -X POST https://www.hitheo.ai/api/v1/hooks \
    -H "Authorization: Bearer $THEO_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "event_pattern": "order.*.completed",
      "skill_slug": "my-order-processor",
      "cooldown_minutes": 5
    }'
  ```

  ```typescript SDK theme={null}
  // Preset
  await theo.createHook({
    hook_preset_id: "share.accepted.welcome",
    skill_slug: "email-drafter",
  });

  // Custom pattern
  await theo.createHook({
    event_pattern: "order.*.completed",
    skill_slug: "my-order-processor",
    cooldown_minutes: 5,
  });
  ```
</CodeGroup>

### 自定义事件模式

模式支持以下形式：

* **精确匹配**：`share.accepted` 仅匹配 `share.accepted`
* **通配符（Glob）**：`order.*.completed` 匹配 `order.purchase.completed`、`order.return.completed`
* **前缀匹配**：`share` 匹配 `share.accepted`、`share.declined` 等
* **全匹配**：`*` 匹配所有事件

### 发布事件

使用 `POST /api/v1/events` 发布领域事件，以触发 Hook 与 Webhook：

```typescript theme={null}
await theo.publishEvent({
  orgId: "your-org-id",
  eventType: "order.purchase.completed",
  payload: { orderId: "ORD-123", total: 299.99 },
});
```

### 护栏

自主执行运行在严格的安全限制之下：

* 每次运行前进行预检额度检查
* 为自主操作单独设置每日上限
* 对工具调用次数与总花费设置单次运行上限
* 各步骤之间设有额度检查点
* Hook 在连续失败后会自动暂停
* 可配置触发之间的冷却时间，以防止失控执行

### 管理 Hook

* `GET /api/v1/hooks` —— 列出 Hook（包含可用预设）
* `PATCH /api/v1/hooks/{id}` —— 更新配置、启用/禁用
* `DELETE /api/v1/hooks/{id}` —— 删除
* `GET /api/v1/hooks/{id}` —— 查看执行历史


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.