创建 Webhook

接口说明

创建 Webhook 订阅，并在创建时返回一次签名密钥。

接口信息

字段	值
方法	POST
路径	/openapi/v2/webhooks
Operation ID	createWebhook
鉴权	Bearer OpenAPI key

入参

名称	位置	必填	类型	示例	说明
Idempotency-Key	header	是	string	mutation-2026-07-10-001	客户端为请求生成的幂等键。重试同一请求时复用相同值，可以避免创建重复任务。

请求体

application/json

字段	必填	类型	示例	说明
name	否	string | null	Source file updates	可选 Webhook 名称。
url	是	string	https://hooks.example.com/focowiki	接收 Webhook 的 HTTPS 地址。
events	是	array<document.waiting | document.processing | document.available | document.error | document.deleting | file.deleted | knowledge_base.deleted>	["document.available","document.error","document.deleting"]	订阅接收的 Webhook 事件类型。

请求示例

curl -X POST "https://openapi.example.com/openapi/v2/webhooks" \
  -H "Authorization: Bearer <openapi-key>" \
  -H "Idempotency-Key: mutation-2026-07-10-001" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "Source file updates",
  "url": "https://hooks.example.com/focowiki",
  "events": [
    "document.available",
    "document.error",
    "document.deleting"
  ]
}'

成功响应

201

返回新 Webhook 订阅及仅本次返回的签名密钥。

字段	必填	类型	说明
webhook	是	object	Webhook 订阅记录。
signingSecret	是	string	仅创建接口返回一次的 Webhook 签名密钥。相同幂等请求会返回同一个值；列表接口不会返回该值。

成功响应示例

{
  "webhook": {
    "webhookId": "webhook-11111111-1111-4111-8111-111111111111",
    "name": "Source file updates",
    "endpointHost": "hooks.example.com",
    "events": [
      "document.available",
      "document.error",
      "document.deleting"
    ],
    "createdAt": "2026-06-17T00:00:00.000Z",
    "lastDeliveryAt": null
  },
  "signingSecret": "<webhook-signing-secret>"
}

错误码

下表列出这个接口已声明的全部错误响应。

HTTP 状态	错误码	说明
401	UNAUTHORIZED	Bearer API key 缺失、格式错误、未知、已撤销或已删除。
413	PAYLOAD_TOO_LARGE	请求体或待读取文件超过当前接口允许的大小。
422	VALIDATION_ERROR	请求未通过校验。
429	RATE_LIMITED	请求超过当前配置的速率限制。
500	INTERNAL_ERROR	API 遇到内部错误。
503	DATABASE_REPOSITORY_UNAVAILABLE	当前接口所需的数据暂时不可用。

后续操作

• 列出投递记录