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