Webhook 集成

两个方向

Rendering diagram…

方向	场景
入站 Inbound	外部系统 → combo agent（触发 Agent 任务）
出站 Outbound	combo agent → 外部系统（事件通知、结果回推）

入站 Webhook

通用接入地址

POST https://<combo-agent>/v1/webhook/generic/{trigger_id}
Content-Type: application/json
X-Combo-Signature: sha256=<hmac>
X-Combo-Timestamp: <unix_seconds>

{ ...任意 payload... }

{trigger_id} 在管理台创建 Event Trigger 时生成。

配置步骤

管理台 → 事件触发 → 新增，选择 generic_webhook
平台生成 URL + Secret
把 URL + Secret 配置到外部系统
在 Trigger 里设置 payload → Agent inputs 的映射（支持 JSONPath）

配置示例：

trigger:
  source: generic_webhook
  secret: "<auto-generated>"
  match:
    # 可选的条件过滤（比如 payload.action == "escalated"）
    jsonpath: "$.action"
    equals: "escalated"
  action:
    agent_id: "ticket-triage"
    inputs:
      ticket_id: "{{ payload.ticket.id }}"
      priority: "{{ payload.ticket.priority }}"
      customer: "{{ payload.ticket.customer }}"

验签（客户端示例）

import hmac, hashlib, time, requests, json
 
secret = "your-webhook-secret"
body = json.dumps({"action": "escalated", "ticket": {...}}).encode()
ts = str(int(time.time()))
sig = "sha256=" + hmac.new(secret.encode(), ts.encode()+b"."+body, hashlib.sha256).hexdigest()
 
requests.post(
    "https://<combo-agent>/v1/webhook/generic/<trigger_id>",
    data=body,
    headers={
        "Content-Type": "application/json",
        "X-Combo-Signature": sig,
        "X-Combo-Timestamp": ts,
    },
)

出站 Webhook

平台把内部事件（Session 完成、工具调用、审查完成…）推送给客户自有系统。

配置步骤

管理台 → 集成 → Webhook 订阅 → 新增
填写：
- URL：客户接收地址（必须 HTTPS）
- Events：勾选订阅的事件
- Secret：平台生成或自定义
平台立即发一条 ping 事件，客户需要返回 2xx

订阅事件目录

事件	说明
`session.created`	新建 Session
`session.finished`	Agent 完成任务
`session.archived`	归档
`tool.called`	工具调用（高频，谨慎订阅）
`tool.error`	工具失败
`review.completed`	代码审查完成
`import.completed`	需求/Bug 导入完成
`cost.threshold_exceeded`	成本超限告警
`hook.violation`	合规 Hook 命中告警

完整字段与 payload 示例见 Webhook 事件参考。

重试 & 死信

Rendering diagram…

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

超过 5 次失败进入死信队列，管理台可手动重放。

消费方要求：

2 秒内返回 2xx
收到后把业务处理放到本地异步队列
相同 event_id 做幂等（网络抖动可能重复投递）

安全

机制	说明
HMAC-SHA256 签名	默认开启，防篡改
时间戳	默认 ±5 分钟偏差，防重放
IP 白名单	可选，仅允许指定出口 IP
mTLS	敏感场景可启用双向 TLS
Secret 轮换	管理台一键轮换，灰度生效 7 天

审计

所有 Webhook（入站 + 出站）都记录在 webhook_audit 表，字段包含：

event_id, direction, trigger_id, url
request_headers_sha, request_body_sha, response_status
duration_ms, retries, ts

管理台「审计 → Webhook」可查询、筛选、重放。

常见问题

Q：入站签名校验失败？ A：确认 Secret 一致；时间戳要用 Unix 秒；body 在签名后不要被中间件改动。

Q：出站偶尔超时？ A：消费方立即返回，业务异步做；保证 2 秒内响应。

Q：事件太多淹没下游？ A：按事件类型订阅，不要订阅 tool.called 这种高频事件，除非下游是日志/观测平台。

Webhook 集成

两个方向

入站 Webhook

通用接入地址

配置步骤

验签（客户端示例）

出站 Webhook

配置步骤

订阅事件目录

重试 & 死信

安全

审计

常见问题

相关文档

On this page