Webhook

Webhook endpoint 允许外部系统向 Agent 的事件流发送事件。每个 Agent 可拥有多个 endpoint，分别对接不同的集成源。

创建 Endpoint

1. 打开 Agent 设置 → Webhooks
2. 输入名称（如 youtube-live、discord）
3. 选择鉴权模式
4. 点击 创建 Webhook

新创建的 webhook 默认为测试模式——传入的 payload 会被保存用于预览，但不会创建事件。这让你可以在正式上线前验证数据格式。

生成的 endpoint URL：

POST /api/ingest/webhook/<webhookId>

测试模式

当 webhook 处于测试模式时：

1. 从外部应用向 endpoint URL 发送真实 payload
2. 在 webhook 卡片上打开配置映射对话框
3. 收到的 payload 会显示在源 Payload 下拉列表中（最多保留最近 10 条）
4. 使用可视化映射编辑器将传入字段映射到事件属性
5. 查看实时预览确认映射结果正确
6. 点击正式上线激活 webhook——之后的 payload 将创建事件

测试模式提供一个安全的环境，让你可以反复调整映射配置，而不会污染事件流。

可视化映射

映射对话框提供两种模式：

可视化模式（推荐）

可视化编辑器展示分栏视图：

• 左侧面板——源 Payload：接收到的 payload 的 JSON 树。当目标字段获得焦点时，点击任意字段即可自动生成映射表达式。
• 右侧面板——目标字段：需要映射的 5 个事件字段：

字段	键	必填	默认模板
Platform	platform	否	{{ payload.platform || 'webhook' }}
Element	element	否	{{ payload.username || 'external' }}
Event Type	event_type	否	{{ payload.event_type || 'message' }}
Title	title	是	{{ payload.message }}
Payload	payload	否	{{ payload }}

目标字段下方会显示使用当前选中的测试 payload 的实时预览。

Agent 看到的内容

这五个映射字段会被组装成 Agent 事件流上下文中的一行：

- [02-21 14:35] [evt_abc123] {platform}/{element} ({event_type}): {title}

例如，当 platform=youtube、element=alice、event_type=message、title=hello from chat 时：

- [02-21 14:35] [evt_abc123] youtube/alice (message): hello from chat

payload 字段存储在数据库中。如果 payload 包含 content 字段，其值会替代 title 显示。Agent 可以引用事件 ID（如 evt_abc123）来回复或执行操作。

点击映射工作流：

1. 点击目标字段输入框使其获得焦点
2. 点击左侧 JSON 树中的节点
3. {{ payload.path.to.field }} 表达式自动插入
4. 实时预览立即更新

原始编辑器模式

切换到原始编辑器标签页直接编辑 JSON。完整映射以 JSON 对象表示，使用 {{ payload.xxx }} 模板语法：

{
  "platform": "{{ payload.platform || 'webhook' }}",
  "element": "{{ payload.username || 'external' }}",
  "event_type": "{{ payload.event_type || 'message' }}",
  "title": "{{ payload.message }}",
  "payload": "{{ payload }}"
}

切换标签页时双向同步。

模板语法

• payload 指代传入的 JSON payload
• payload.path.to.field 访问嵌套字段（支持对象和数组，如 payload.items.0.name）
• || 链提供回退值
• 'literal' 作为字面量使用
• {{ payload }} 传递整个 payload 对象

映射必须生成非空的 title 字段。否则 ingest 会返回 422 错误。

鉴权模式

模式	安全性	适用场景
open	无	测试、低风险内部来源
api_key	header/query/body 中的 key	可发送 key 但无法签名的集成
secret	基于 key 的验证	生产环境推荐

api_key 和 secret 模式下，key 按以下顺序检测：

1. Authorization: Bearer <key> header
2. X-Webhook-Key、X-API-Key、X-Webhook-Secret header
3. Query 参数：key、api_key、secret、token
4. JSON body 字段：key、api_key、secret、token

这种灵活性使无法设置自定义 header 的来源（如 Social Stream Ninja）也能通过 JSON body 或 query 传递 key。

警告

open 模式没有鉴权——任何知道 endpoint URL 的人都可以发送事件。请仅在测试时使用。

敏感字段剥离

在测试模式下，保存的 payload 会自动剥离鉴权相关字段，避免在 UI 中泄露凭证。默认剥离以下字段：

key、api_key、secret、token、password、authorization、access_token、refresh_token、bearer

你可以在 webhook 设置中配置额外的排除字段。用户配置的排除在测试模式和正式模式下均生效。

Endpoint 生命周期

状态流转

Webhook 可处于以下三种状态：

状态	标签颜色	行为
测试中	琥珀色	Payload 保存用于预览，不创建事件
已激活	绿色	Payload 经映射后写入 events 表
已禁用	灰色	Endpoint 以 404 拒绝所有请求

可用的状态转换：

• 测试中 → 正式上线（已激活）或禁用
• 已激活 → 暂停（已禁用）或测试模式（测试中）
• 已禁用 → 启用（已激活）

轮转

轮转会生成新的 endpoint ID 和 key，同时禁用旧的。当 key 可能泄露时使用：

1. 在 endpoint 卡片上点击 轮转
2. 生成新的 endpoint ID 和 key
3. 旧 endpoint 立即被禁用
4. 用新 URL/key 更新发送端

删除

删除后的 endpoint 立即返回 404，不可再接收事件。

限流

每个 endpoint 有限流配置（默认：120 请求/分钟）。超出后返回 429 Rate limit exceeded。

接入 Social Stream Ninja

Social Stream Ninja 可聚合 100+ 平台（YouTube、Twitch、TikTok 等）的直播事件并转发到 webhook。

无 Header 场景的接入步骤

Social Stream Ninja 可能不支持自定义 HTTP header。使用 api_key 模式，将 key 放在 JSON body 中：

1. 以 api_key 鉴权模式创建 endpoint
2. 复制生成的 key
3. 在 Social Stream Ninja 中配置 webhook URL：

   https://your-domain/api/ingest/webhook/<webhookId>

4. 在 JSON payload 中以 key 字段传入 key

Payload 示例

{
  "platform": "youtube",
  "username": "alice",
  "message": "hello from chat",
  "event_type": "message",
  "key": "your-api-key-here"
}

错误码

错误码	状态码	说明
WEBHOOK_NOT_FOUND	404	endpoint 不存在或已禁用/删除
WEBHOOK_UNAUTHORIZED	401	key 缺失或无效
WEBHOOK_MAPPING_INVALID	422	映射结果无效（如缺少 title）
WEBHOOK_RATE_LIMITED	429	超出限流
WEBHOOK_INGEST_FAILED	500	服务器错误

相关

• 事件流概念