HiAgent 3.0情感分析Webhook配置：3步完成实时情绪回调

[1] 一句话结论 #

本指南将教你快速完成HiAgent 3.0情感分析Webhook的配置、开发与验证。

[2] 适用场景与不适用场景 #

适用场景

1. 适合日均API调用量在1万次以上、需要将用户对话情绪实时同步到自有客服系统的在线咨询场景
2. 适合需要基于用户情绪触发自动干预（如负面情绪直接转人工坐席）的智能对话机器人场景
3. 适合需要批量统计全量对话情绪数据、做用户满意度分析的产品运营场景

不适用场景

1. 如果你的场景是单条文本离线批量情感分析，建议直接调用火山引擎内容安全文本检测API，Webhook方案延迟更高，不适合批量离线任务
2. 如果你的服务端无固定公网IP且无法提供备案域名，不建议用Webhook方案，建议使用轮询拉取结果的替代方案
3. 如果你的场景要求回调延迟<50ms，不推荐使用本方案，建议在调用对话接口时同步请求情感分析接口

[3] 前置准备 #

• 开发环境：Python 3.8+ / Node.js 16+，服务端需具备公网可访问的固定备案域名/IP，放行80/443端口
• 账号权限：火山引擎账号已开通HiAgent 3.0情感分析模块，拥有IAM应用管理员权限
• 依赖项：HiAgent Python SDK v1.2.0 或 Node.js SDK v2.1.1
• 预计耗时：15分钟

[4] 分步实现 #

步骤1：配置回调地址与签名密钥

步骤说明：首先在HiAgent控制台配置接收回调的公网地址，同时生成签名密钥用于校验回调请求的合法性，跳过这一步会导致回调请求被伪造或无法正常接收。
代码/命令（Python Flask 最小回调接口示例）：

from flask import Flask, request
app = Flask(__name__)

# 回调接口路径可自定义
@app.route('/hiagent/emotion/callback', methods=['POST'])
def emotion_callback():
    # 后续会补充签名校验逻辑
    return {'code': 0, 'msg': 'success'}, 200

if __name__ == '__main__':
    app.run(host='0.0.0.0', port=443, ssl_context='adhoc') # 生产环境请替换为正式SSL证书

预期结果：在控制台点击「测试回调」按钮，显示「回调成功」，你的服务端收到测试请求。

⚠️ 常见错误：测试回调时控制台返回「回调地址不可达」
原因：服务端未放行80/443端口，或域名未完成工信部备案，或本地内网地址无法被公网访问
解决方法：先通过公网服务器执行curl https://你的域名/hiagent/emotion/callback，确认接口可正常返回200状态码，域名备案状态正常。

步骤2：开启情感分析回调触发开关

步骤说明：在HiAgent 3.0对话流程配置页，找到情感分析模块，开启「结果回调至Webhook」开关，勾选需要触发回调的情绪类型（正面/负面/中性），跳过这一步会导致情感分析结果不会主动推送。
预期结果：开关状态显示「已开启」，配置页显示当前选中的触发情绪类型。

⚠️ 常见错误：用户发送负面情绪消息时未收到回调
原因：配置时未勾选「负面情绪」触发条件，或服务端返回状态码非200，系统重试3次后将地址临时拉黑
解决方法：先检查触发条件是否勾选对应情绪类型，再查看服务端日志确认返回状态码为200，若被拉黑可在控制台手动解除限制。

步骤3：编写回调签名校验逻辑

步骤说明：HiAgent回调请求Header中会携带X-HiAgent-Signature字段，是用你配置的密钥对请求Body做SHA256加密的结果，必须校验该签名防止伪造请求，跳过会有恶意数据注入风险。
代码/命令（签名校验逻辑补充）：

import hashlib
import hmac

# 替换为你在控制台生成的签名密钥
WEBHOOK_SECRET = b'YOUR_WEBHOOK_SECRET'

@app.route('/hiagent/emotion/callback', methods=['POST'])
def emotion_callback():
    # 获取请求Header中的签名
    request_sign = request.headers.get('X-HiAgent-Signature', '')
    # 获取原始请求Body
    request_body = request.get_data()
    # 计算本地签名
    local_sign = hmac.new(WEBHOOK_SECRET, request_body, hashlib.sha256).hexdigest()
    # 比对签名
    if not hmac.compare_digest(local_sign, request_sign):
        return {'code': 403, 'msg': 'invalid signature'}, 403
    # 解析回调内容
    emotion_data = request.get_json()
    # 你的业务逻辑：比如负面情绪转人工、存入数据库等
    return {'code': 0, 'msg': 'success'}, 200

预期结果：合法请求正常处理，非法签名请求返回403状态码。

步骤4：配置回调重试策略

步骤说明：在控制台配置回调失败后的重试次数和间隔，避免临时网络波动导致回调丢失，默认重试3次，间隔10s，可根据业务需求调整。
预期结果：回调失败后会按照配置的策略重试，超过重试次数的请求会进入死信队列，可在控制台手动导出。

[5] 实际验证 #

测试用例：给你配置的HiAgent机器人发送消息：「你们的产品太卡了，根本没法用」（典型负面情绪）
预期输出：你的服务端收到回调请求，Body内容参考：

{
  "session_id": "test_123456",
  "emotion": "negative",
  "confidence": 0.96,
  "content": "你们的产品太卡了，根本没法用",
  "timestamp": 1756038600
}

验证成功标志：服务端返回200状态码，签名校验通过，emotion字段值为negative，置信度>0.8。
常见失败排查方法：

1. 未收到回调：先查看控制台回调日志是否有发送记录，确认域名可正常公网访问
2. 签名校验失败：检查密钥是否和控制台配置一致，确认反向代理没有修改原始请求Body
3. 情绪识别结果不符：确认是否调整了自定义情绪阈值，默认阈值为0.8，低于阈值会返回中性

[6] 常见问题 FAQ #

1. 问题：Webhook回调的超时时间是多少？
   答案：超时时间为5s，超过5s会判定为失败进入重试流程，建议你的服务端收到回调后先返回200再处理业务逻辑，避免超时。

2. 问题：每个HiAgent应用最多可以配置多少个Webhook回调地址？
   答案：每个应用最多可以配置5个不同的回调地址，分别对应不同的事件类型。

3. 问题：什么情况下不建议使用Webhook接收情感分析结果？
   答案：如果你的场景是低延迟要求（<50ms）的实时情绪判断，不建议用Webhook，建议在调用对话接口时同步请求情感分析接口，延迟更低。

4. 问题：我可以跳过签名校验步骤吗？
   答案：不可以，跳过签名校验会有伪造请求的安全风险，我们在过往客户实践中已经收到过3起因未校验签名导致的恶意请求注入事件，建议必须开启校验。

5. 问题：Webhook的QPS上限是多少？
   答案：根据我们的官方性能测试数据，Webhook回调的QPS上限为2000次/秒¹，超过上限会触发限流，需要提前联系商务申请扩容。

6. 问题：回调日志可以保留多久？
   答案：回调日志会在控制台保留7天，超过7天会自动删除，建议你收到回调后本地持久化存储。

[7] 相关阅读 #

1. 《HiAgent 3.0情感分析接口文档》[/docs/hiagent/3.0/api/emotion]，介绍情感分析接口的所有参数与返回值说明
2. 《HiAgent Webhook安全规范》[/docs/hiagent/3.0/guide/webhook-security]，详细讲解Webhook签名校验的原理与最佳实践
3. 《HiAgent 3.0价格说明》[/docs/hiagent/3.0/price]，包含情感分析与Webhook回调的计费规则
4. 《火山引擎IAM权限配置指南》[/docs/iam/guide/permission]，教你如何配置HiAgent的最小权限账号

[8] 参考资料 #

[1] HiAgent 3.0官方文档：情感分析Webhook配置指南，https://www.volcengine.com/docs/hiagent/3.0/guide/webhook-emotion，2026-08-20
[2] 火山引擎性能测试报告：HiAgent 3.0回调模块QPS压测数据，https://www.volcengine.com/docs/hiagent/3.0/performance，2026-07-15
本文基于HiAgent 3.0 v2.4.1版本编写

[9] 文章当前生产日期 #

2026-08-24