Webhook 触发器 API

工作流文档绑定「Webhook 触发」模板并发布后，系统会生成一个带密钥鉴权的外部触发地址。外部系统 POST 调用即可触发已发布版本运行，POST body 作为 payload 输入传入工作流。

基础信息

• 基础路径：/api/webhook-triggers
• 触发端点认证：Webhook Secret（Authorization: Bearer <secret> 或 X-Webhook-Secret 头）
• 管理端点认证：JWT Bearer Token 或 API Key（combinedAuth）

语义与边界

• 触发器仅对已发布版本生效：每次发布会把触发器指向最新 deployment；修改文档后需重新发布。
• 密钥仅存哈希（sha256），明文只在生成/轮换时返回一次，丢失需重新轮换。
• 未生成密钥前外部调用一律拒绝（fail-closed）。
• 鉴权失败（地址不存在 / 密钥错误 / 已停用 / 未生成密钥 / 发布版本已删）统一返回 404 同响应体，防资源枚举。
• 端点按 webhook 维度限流（默认 60 次/分钟，管理后台 site_settings.webhook_trigger.rate_limit 可调），超限返回 429。
• 运行的工作流可通过 _trigger 输入读取触发上下文（source='webhook'、webhook_id、triggered_at 等）。
• 大体积数据建议通过文件引用（wnfile:）传递，避免运行记录膨胀；POST body 受运行输入体积上限约束。

端点

POST /api/webhook-triggers/:webhookId

外部触发工作流运行（同步执行，非流式 JSON 响应）。

认证：Authorization: Bearer <secret> 或 X-Webhook-Secret: <secret>。

请求：JSON body 整体作为工作流的 payload 输入传入；空 body 视为 {}。

curl -X POST "https://<api-base>/api/webhook-triggers/<webhookId>" \
  -H "Authorization: Bearer wht_..." \
  -H "Content-Type: application/json" \
  -d '{"order_id": 42}'

响应：与 /api/released-app/:deploymentId/run 非流式响应一致（含 runId、sessions 等执行结果）。

错误：

状态码	code	含义
404	webhook_not_found	地址不存在 / 密钥错误 / 已停用 / 未生成密钥 / 发布版本已删（统一防枚举）
402	insufficient_credits	发布团队积分不足
403	-	触发器无可计费团队（需重新发布）
413	-	请求体超过运行输入体积上限
429	-	触发频率超限

GET /api/webhook-triggers/by-document/:documentId

查询文档的 Webhook 触发器信息（需项目访问权限）。

响应：

{
  "exists": true,
  "id": "uuid",
  "enabled": true,
  "path": "/api/webhook-triggers/<id>",
  "hasSecret": true,
  "secretPrefix": "wht_1234abcd",
  "deploymentId": "uuid",
  "lastTriggeredAt": "2026-06-10T12:00:00Z"
}

path 为相对路径，完整 URL 由前端用统一 API base 拼接；接口不返回密钥明文或哈希。

POST /api/webhook-triggers/by-document/:documentId/rotate-secret

生成或轮换 Webhook 密钥（需项目管理员权限或文档 owner）。

响应：

{
  "id": "uuid",
  "path": "/api/webhook-triggers/<id>",
  "secret": "wht_..."
}

secret 明文仅本次响应返回，库中只存 sha256 哈希，不可找回。

错误：

状态码	code	含义
400	webhook_trigger_missing	文档尚未绑定 Webhook 触发器或尚未发布
403	-	需要项目管理员权限