集成：Webhook 与 WebSocket

欣悦互通提供多种集成方式，方便将平台能力接入您的业务系统。通过 Webhook 接收事件通知、通过 WebSocket 获取实时状态推送、通过 RAG 知识库增强 AI 检索能力，构建完整的自动化工作流。

本篇介绍 Webhook 配置、WebSocket 实时通信、RAG 知识库集成三方面内容。

Webhook 配置

Webhook 允许欣悦互通在特定事件发生时，主动向您的服务器发送 HTTP POST 请求，实现事件驱动的自动化响应。

支持的事件类型

配置 Webhook

1. 进入「系统设置 → Webhook 配置」。
2. 点击「新增 Webhook」。
3. 填写配置：
   • 回调 URL（您的服务端地址）
   • 订阅事件（可多选）
   • Secret 密钥（用于签名校验）
4. 点击「确定」保存。

配置后，每次事件触发时系统会向回调 URL 发送 POST 请求：

POST /your/webhook/endpoint HTTP/1.1
Content-Type: application/json
X-XYHT-Signature: sha256=xxxxxxxxxxxx

{
  "event": "content.published",
  "timestamp": 1750723200,
  "data": {
    "contentId": 123,
    "platform": "wechat",
    "status": "success"
  }
}

!WARNING

• 回调 URL 必须为 HTTPS，且响应时间不超过 5 秒。
• 如连续失败 10 次，Webhook 将自动禁用，需手动启用。

签名校验

为防止伪造请求，建议在服务端校验签名：

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(expected),
    Buffer.from(signature)
  );
}

!TIP

• Webhook 请求若返回非 2xx 状态码，系统会按 1/5/30/60/300 分钟间隔重试 5 次。
• 建议您的服务端先快速返回 200，再异步处理业务逻辑，避免超时。

WebSocket 实时通信

WebSocket 提供双向实时通信能力，适用于需要即时状态更新的场景。

连接 WebSocket

const ws = new WebSocket('wss://api.example.com/api/ws', {
  headers: { Authorization: 'Bearer ' + apiKey }
});

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  console.log(message.type, message.data);
};

支持的消息类型

!NOTE

• WebSocket 连接需携带有效的 API 密钥或 JWT Token 进行认证。
• 连接空闲超过 60 秒会发送心跳包保持连接，请妥善处理 ping/pong。

集成最佳实践

• 前端页面可订阅 agent_status 和 workflow_progress，实时展示 AAO 执行进度。
• 通知中心可订阅 notification，实现新消息实时推送，无需轮询。
• 导航栏可订阅 unread_count（按 user_id 过滤），实时更新未读消息角标。

RAG 知识库集成

RAG（检索增强生成）知识库通过向量化您自有文档，让 AI 在对话和分析时引用您的业务知识，提升回答准确性和相关性。

知识库管理

1. 进入「AI 中心 → RAG 知识库」。
2. 点击「新增知识库项」，上传文档（支持 txt、md、pdf、docx）。
3. 系统自动切片、向量化并建立索引。
4. 在列表中查看索引状态和统计信息。

知识库通过 GET/POST /api/rag/knowledge 管理，DELETE /api/rag/knowledge/{id} 删除。

索引任务

1. 在「索引任务」页查看向量化任务列表和状态。
2. 失败的任务可点击「重试」重新执行。
3. 支持重建全部索引（POST /api/rag/knowledge/reindex）。

索引任务通过 GET/POST /api/rag/tasks 管理，POST /api/rag/tasks/{id}/retry 重试。

向量检索

在 AI 对话或内容生成时，系统会自动检索知识库并注入相关上下文。也可手动调用检索接口测试：

POST /api/rag/search HTTP/1.1
Content-Type: application/json

{
  "query": "品牌的核心价值主张",
  "topK": 5
}

RAG 配置

通过 GET/PUT /api/rag/config 配置 RAG 参数：

• 嵌入模型（Embedding Model）
• 检索 Top-K 数量
• 相似度阈值
• 分块大小和重叠

!TIP

• 建议为不同业务领域创建独立知识库项，便于检索精准匹配。
• 文档更新后需重建索引，系统支持增量索引，仅处理变更部分。

集成最佳实践

1. 事件驱动架构

使用 Webhook 接收事件，结合自有系统实现自动化：内容发布完成 → 触发 Webhook → 同步到自有 CMS → 发送用户通知。

2. 实时状态展示

前端页面通过 WebSocket 订阅状态推送，避免轮询 API，降低服务器压力并提升用户体验。

3. 知识库增强 AI

将企业产品文档、品牌手册、常见问题上传到 RAG 知识库，AI 对话和内容生成时会自动引用，确保输出符合品牌调性。

4. 安全与限流

• Webhook 回调 URL 启用签名校验，防止伪造。
• WebSocket 连接认证后生效，密钥泄露后立即吊销。
• RAG 检索受 API 配额约束，合理控制调用频率。

相关链接

• API 密钥管理
• AI 能力
• AAO 自动化
• 配额与用量预警
• 常见问题 FAQ