Webhook 事件

Webhook 的两个方向

Rendering diagram…

入站事件（外部 → 平台）

外部系统把事件发到平台的 Webhook URL，平台验签后路由到 Event Trigger / Session。

通用格式

POST /v1/webhook/{channel}
Content-Type: application/json
X-Combo-Signature: sha256=<hmac>
X-Combo-Timestamp: 1699999999
X-Combo-Event-Id: <unique-id>
 
{ ...channel 专用 payload... }

验签

HMAC-SHA256 基于请求体 + 时间戳，密钥在平台「集成 → Webhook」配置时生成。

import hmac
import hashlib
 
def verify(body: bytes, timestamp: str, signature: str, secret: str) -> bool:
    payload = timestamp.encode() + b"." + body
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

支持的入站 Channel

Channel	Path	说明
飞书事件订阅	`/v1/webhook/lark`	消息 / 审批 / 日历变更
企微事件订阅	`/v1/webhook/wecom`	消息 / 通讯录变更
Gerrit Hook	`/v1/webhook/gerrit`	`patchset-created` / `change-merged` 等
GitLab Webhook	`/v1/webhook/gitlab`	Push / MR / Pipeline
GitHub Webhook	`/v1/webhook/github`	Push / PR / Issue
Gitee Webhook	`/v1/webhook/gitee`	同 GitHub
通用 Webhook	`/v1/webhook/generic/{trigger_id}`	自定义触发器（按配置）

平台出站事件

平台可以把内部事件推送给客户自有系统。

订阅出站事件

POST /v1/webhook/subscriptions
Content-Type: application/json
 
{
  "url": "https://client.example.com/combo-callback",
  "events": ["session.finished", "tool.called"],
  "secret": "your-shared-secret"
}

出站事件类型

事件	触发时机	payload 关键字段
`session.created`	新建 Session	`session_id`, `tenant_id`, `user_id`
`session.finished`	Agent 完成任务	`session_id`, `cost`, `artifacts`
`session.archived`	Session 归档	`session_id`
`tool.called`	工具被调用	`tool_name`, `session_id`, `args_hash`
`tool.error`	工具失败	`tool_name`, `error`, `session_id`
`agent.step`	Agent 推进一步（verbose）	`action`, `confidence`, `session_id`
`review.completed`	代码审查完成	`pr_url`, `report_url`, `issues_found`
`import.completed`	需求 / Bug 导入完成	`source`, `count`, `errors`
`cost.threshold_exceeded`	成本超限	`tenant_id`, `period`, `amount`

出站 Payload 示例

{
  "event": "review.completed",
  "event_id": "evt_abc123",
  "timestamp": "2026-04-23T10:15:00Z",
  "tenant_id": "t_corp_a",
  "data": {
    "session_id": "sess_xyz",
    "pr_url": "https://gerrit.../c/12345",
    "report_url": "https://combo.../sessions/sess_xyz/report",
    "issues_found": {
      "critical": 2,
      "warning": 5,
      "info": 12
    },
    "cost": { "tokens": 8320, "duration_ms": 45000 }
  }
}

重试策略

出站 Webhook 的重试：

次数	间隔
1	即时
2	30 秒
3	2 分钟
4	10 分钟
5	1 小时

消费方必须 2 秒内返回 2xx，否则视为失败。超过 5 次重试失败的事件进入"死信队列"，可在管理台手动重放。

Event Trigger：把入站事件变成 Agent 任务

入站 Webhook 可以配置为 Event Trigger，自动触发 Agent：

# 示例配置
trigger:
  source: gerrit
  match:
    event: patchset-created
    project_regex: "^platform/.*"
  action:
    agent_id: "code-review-agent"
    session_template: "code-review-session"
    inputs:
      pr_url: "{{ event.change.url }}"
      change_id: "{{ event.change.number }}"

常见问题

Q：入站 Webhook 验签失败？ A：检查密钥配置；检查时间戳偏差（平台默认允许 ±5 分钟）；检查 body 是否未被中间件改写。

Q：出站 Webhook 消费方偶尔超时怎么办？ A：消费方收到后应立即返回 200，业务处理放到本地异步队列；不要在 Webhook 同步里做长流程。

Q：能不能重放历史事件？ A：能。管理台「集成 → Webhook → 历史事件」可按时间范围筛选后重放。