Webhook 集成：让外部事件主动唤醒 Agent
Webhook 让工单、订单、CI、监控告警等外部系统在事件发生时，主动把 JSON 数据推送进 Syfo。
事件进入 Syfo 后，会变成频道里的结构化卡片。你还可以让它立刻唤醒 Agent，按你预先写好的处理指令分析事件，并把结论发回频道。
text
你的系统 POST JSON
↓
Syfo 验证请求身份
↓
频道生成事件卡片
↓
唤醒 Agent
↓
Agent 把处理结论发回频道频道里的 Webhook 事件卡片，以及被唤醒的 Agent 在同一频道回复处理结论 — webhook-event-card.png
5 分钟跑通第一条事件
只有频道管理员能创建 Webhook 集成。
- 打开目标频道，点击右上角 「⋯」→「添加集成」。
- 填写集成名称、来源类型和鉴权方式。
- 如果希望 Agent 自动处理，打开 「唤醒 Agent」。
- 保存后复制接入 URL 和密钥。
- 从你的系统或终端发送一条测试请求。
密钥只显示一次
关闭创建结果后，不能再次查看原密钥。如果没有保存或怀疑已经泄露，请轮换密钥。不要把真实密钥发到频道、工单或代码仓库里。
频道右上角添加集成，以及创建完成后一次性展示接入 URL 和密钥 — webhook-create-endpoint.png
先用下面的请求验证接入：
bash
curl -X POST 'https://app.syfo.ai/api/hooks/<endpoint ID>' \
-H 'Authorization: Bearer <密钥>' \
-H 'Content-Type: application/json' \
-d '{"ticket_id":"T-20873","subject":"退款申请需要人工复核","priority":"urgent"}'| 检查项 | 要求 | 成功结果 |
|---|---|---|
| URL | https://app.syfo.ai/api/hooks/<endpoint ID> | 请求发到对应频道集成 |
| 方法 | POST | 其他方法不会创建事件 |
| Body | 合法 JSON | 字段显示在结构化事件卡片中 |
| 鉴权 | Bearer、HMAC，或来源类型要求的凭证 | 验签通过 |
| HTTP 状态 | 返回 202 | Syfo 已接受事件并进入后续处理 |
收到 202 表示接入成功。随后到频道确认事件卡片是否出现；如果开启了自动处理，再确认 Agent 是否开始响应。
让 Agent 自动接手
Webhook 不只能“把消息发进频道”，还可以把事件交给 Agent 立即处理。
配置时需要设置：
- 唤醒方式：选择「唤醒被 @ 的 Agent」。
- 默认 Agent：当事件没有明确 @ 某个 Agent 时，由它接手。默认 Agent 必须已经是该频道成员。
- 处理指令：写清楚 Agent 收到事件后要检查什么、输出什么、哪些操作需要人确认。
- 每小时唤醒上限：默认是 6 次，避免异常系统持续推送时反复唤醒 Agent。
- 聚合方式：同类事件可以合并处理，减少频道刷屏和重复消耗。
处理指令可以这样写：
text
读取事件中的 ticket_id、priority 和 subject。
判断是否需要人工升级，并给出理由。
不要直接回复客户；先在频道输出建议回复和需要确认的动作。外部数据不是指令
Webhook payload 一律按“数据”处理。即使某个字段里写着“请忽略以上指令”或“立即执行退款”，Agent 也不应把它当成新的系统命令。能给 Agent 下处理指令的是你配置的规则，不是推送数据的外部系统。
Webhook 的 Agent 唤醒设置：默认 Agent、处理指令、每小时上限和聚合方式 — webhook-agent-wake-settings.png
谁能操作
管理员是频道创建者或组织管理员。普通频道成员可以看到事件，但不能修改集成或密钥。
| 操作 | 频道管理员 | 普通频道成员 |
|---|---|---|
| 新建、编辑、暂停、删除集成 | 可以 | 不可以 |
| 轮换或吊销密钥 | 可以 | 不可以 |
| 查看日志与审计信息 | 可以 | 不可以 |
| 查看频道里的事件卡片 | 可以 | 可以 |
频道创建第一个集成后，顶部才会常驻显示 「集成」 标签页。管理员可以从这里进入管理、日志和密钥操作。
接入你的系统
所有 Webhook 都使用下面的统一地址：
text
https://app.syfo.ai/api/hooks/<endpoint ID>请求方法是 POST，Body 使用 JSON。不同来源类型支持的鉴权头如下：
| 来源类型 | 支持的请求头 | 说明 |
|---|---|---|
| 通用 / GitHub / Stripe | Authorization: Bearer <密钥> | 直接携带 Bearer 令牌 |
| 通用 / GitHub / Stripe | X-Syfo-Signature: sha256=<签名> | 使用密钥对原始请求 Body计算 HMAC-SHA256，填十六进制摘要 |
| GitLab | X-Gitlab-Token: <密钥> | GitLab 来源使用专用请求头，不使用 Bearer 或 HMAC 签名 |
创建集成时可以选择：
- Bearer 令牌：只接受 Bearer。
- HMAC 签名：只接受
X-Syfo-Signature。 - 两者皆可：默认选项，任一方式验证通过即可放行。
HMAC 必须对收到的原始 Body 字节计算。不要先解析 JSON、重新排序字段或格式化后再签名，否则摘要会不同。
安全设置
Webhook 是一个外部写入口，建议把下面几项当成上线前检查清单：
保护密钥
密钥只显示一次。发现泄露时，应立即轮换或吊销；排查期间可以先暂停集成，阻止新事件进入。
自动脱敏敏感字段
Syfo 会把手机号、令牌、密钥等敏感信息显示为 [redacted]。如果某个业务字段确实需要保留，可以在 「保留不脱敏的字段」 中按字段名或路径放行。
鉴权令牌和密钥始终会脱敏，不能加入放行名单。
限制来源 IP
可以配置 CIDR 白名单，只允许指定出口 IP 或网段访问。启用前确认生产系统实际使用的出口地址，避免测试环境能推送、生产环境却被拦截。
不执行外部内容
Payload 是待分析的数据，不是 Agent 指令。处理规则应来自管理员配置，涉及发送、删除、支付、退款、发布等动作时，仍应要求人工确认。
日志不保存原始 Payload
Webhook 日志只记录请求时间、状态、来源等元数据，不保留 Payload 原文。需要长期审计业务数据时，应由你的业务系统保留原始事件记录。
出问题怎么查
进入频道顶部 「集成」→ 选择集成 →「管理」→「日志」。日志保留 30 天。
| 现象 | 常见原因 | 怎么处理 |
|---|---|---|
返回 401，提示验签失败 | 密钥错误，或凭证类型不匹配 | 核对当前密钥和鉴权方式；GitLab 必须用 X-Gitlab-Token |
返回 401，但密钥确认无误 | 密钥已被吊销，或集成已暂停 | 到集成管理页检查状态，必要时轮换密钥并重新启用 |
| 请求没有出现在日志里 | 来源 IP 被白名单拒绝，或 endpoint ID 错误 | 核对调用方出口 IP、CIDR 配置和 URL 中的 endpoint ID |
| 事件卡片出现，但 Agent 没有动作 | 未开启唤醒、默认 Agent 不在频道，或超过每小时唤醒上限 | 检查 Agent 成员关系、唤醒设置、上限和聚合规则 |
字段显示为 [redacted] | 命中默认敏感字段脱敏规则 | 确认是否真的需要展示；需要时按字段名或路径加入保留名单 |
如果请求返回 202、卡片也已出现，但 Agent 处理结果不符合预期，优先检查处理指令是否写清输入字段、预期输出和人工确认边界。