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

> 註冊一個新的 Webhook 端點以接收實時事件通知。

## 請求

<ParamField body="url" type="string" required>
  用於接收事件推送的 HTTPS URL。生產環境中必須使用 `https://`。該地址會經過 SSRF 校驗——私有 IP、雲元數據端點以及非 HTTP 協議均會被攔截。
</ParamField>

<ParamField body="event_types" type="string[]" required>
  要訂閱的事件類型數組。使用 `"*"` 訂閱所有事件，或指定具體類型，如 `"completion.created"`。

  有效類型：`completion.created`、`job.completed`、`job.failed`、`workflow.completed`、`workflow.failed`、`skill.installed`、`skill.uninstalled`、`skill.submitted`、`skill.approved`、`skill.rejected`、`skill.suspended`、`connector.created`、`connector.status_changed`、`credits.low`、`key.created`、`key.revoked`、`*`
</ParamField>

<ParamField body="secret" type="string" optional>
  可選的自定義簽名密鑰（16–256 個字符）。若省略，將生成一個密碼學隨機的 32 字節十六進制密鑰。
</ParamField>

<ParamField body="description" type="string" optional>
  Webhook 的可選描述（最多 256 個字符）。
</ParamField>

## 響應

<ResponseField name="id" type="string">
  該 Webhook 的唯一 UUID。
</ResponseField>

<ResponseField name="url" type="string">
  已註冊的端點 URL。
</ResponseField>

<ResponseField name="event_types" type="string[]">
  已訂閱的事件類型。
</ResponseField>

<ResponseField name="enabled" type="boolean">
  創建時始終為 `true`。
</ResponseField>

<ResponseField name="signing_secret" type="string">
  HMAC-SHA256 簽名密鑰。**僅顯示一次——請立即保存。** 用於在你的服務器上驗證 Webhook 簽名。
</ResponseField>

<ResponseField name="created_at" type="string">
  ISO 8601 時間戳。
</ResponseField>

## 身份驗證

需要具有 `completions` 權限範圍的組織級 API 密鑰。

```bash theme={null}
Authorization: Bearer theo_sk_...
```

## 示例

<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}
  import Theo from "@hitheo/sdk";

  const theo = new Theo({ apiKey: process.env.THEO_API_KEY });

  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
  console.log("Signing secret:", webhook.signing_secret);
  ```
</CodeGroup>

### 響應

```json theme={null}
{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "url": "https://your-server.com/webhooks/theo",
  "event_types": ["completion.created", "job.completed"],
  "enabled": true,
  "signing_secret": "8f3a1b2c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b1c2d3e4f5a6b7c8d9e0f1",
  "created_at": "2026-04-15T12:00:00.000Z",
  "_note": "Save the signing_secret — it will not be shown again."
}
```

## 限制

* 每個組織可創建的活躍 Webhook 數量有上限。如需更高配額，請聯繫支持團隊。
* URL 必須通過 SSRF 校驗（不允許私有 IP，不允許雲元數據端點）。
* 生產環境中必須使用 HTTPS。

## 簽名驗證

每次推送都會包含三個用於驗證的請求頭：

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

驗證方式為計算 `HMAC-SHA256(signing_secret, timestamp + "." + raw_body)` 並與簽名進行比對。若時間戳與你本地時鐘相差超過 5 分鐘，應拒絕該請求。

```javascript theme={null}
const crypto = require("crypto");

function verifyWebhook(rawBody, headers, secret) {
  const timestamp = headers["theo-webhook-timestamp"];
  const signature = headers["theo-webhook-signature"];

  // Replay protection
  const age = Math.abs(Date.now() / 1000 - Number(timestamp));
  if (age > 300) throw new Error("Timestamp too old");

  const expected = crypto
    .createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");

  const [, hash] = signature.split("=");
  if (hash !== expected) throw new Error("Invalid signature");

  return JSON.parse(rawBody);
}
```


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