Webhooks：事件回调

快速阅读

Webhook 是呼叫中心在事件发生后，主动 HTTP 访问企业接收地址的事件回调。企业先配好目标地址和推送动作，运行时按类型、条件、超时和重试把数据送出去；通话事实仍以话单为准。

• 管理端入口：企业配置 → 高级设置 → 推送设置。也可通过 OpenAPI 维护同一套对象。
• 先建目标接口（URL、GET / POST、表单 / JSON、超时），再按事件类型建推送动作并启用。
• 接收方建议返回 HTTP 200，并按 mainUniqueId / uniqueId 做幂等；必须能忽略尚未识别的事件类型。
• 查送达看事件回调日志（页面常叫推送日志）和 Webhook 监控。失败不代表通话没发生。
• 工作台里的 AgentSDK 事件、服务端 SDK 控通话、OpenAPI 回拉话单，都不是本页这条 HTTP 回调。

阅读地图

• 先分清和推送产品、工作台事件、服务端 SDK 的边界：读“二”和“九”。
• 要配地址、类型、超时和重试：读“六”。
• 要看什么时候真正发出去：读“四”和“六、3”。
• 要联调和验收：读“八”和“附录 C”。

一、文档说明

客户要把响铃弹屏、接通写回 CRM、挂机同步工单、话单或录音状态交给自建系统时，通常不是让业务系统来轮询，而是让呼叫中心在事件发生时回调企业 URL。

本文说明这条 HTTP 事件回调怎么定位、先配什么、何时生效、失败怎么看。逐类型参数、条件表达式和加工脚本建议结合 推送产品 一起确认；送达对账看 事件回调日志。

适用：对接 CRM / 工单 / 自建中台的技术负责人、实施顾问、需要确认事件是否发出的运营管理员。

二、产品总览

Webhook 的对象是已经发生的事件通知，不是座席工作台里的本地事件，也不是服务端去改这一通怎么接、怎么转。

企业给一个 http:// 或 https:// 地址，选定事件类型；呼叫中心在来电、响铃、接通、挂机、座席状态、话单、录音等节点按配置把参数推过去，并记下对方回了什么。

三、核心概念

四、对象关系与运行链路

管理端或 OpenAPI
  目标接口（URL / 方法 / 格式 / 超时）
  推送动作（类型 / 启用 / 参数 / 条件 / 重试 / 延迟）
        ↓
运行时事件发生（来电、响铃、接通、挂机、状态、话单、录音…）
        ↓
匹配已启用动作 → 判断条件 → 组装参数（可选加工、加密）
        ↓
HTTP GET 或 POST 到企业 URL
        ↓
企业接口响应 → 写入事件回调日志
        ↓
失败则按重试策略再发；仍失败可在日志里人工重推

四个层次不要混：

改 URL 或停用动作，对之后发生的事件生效。已经失败的记录不会因为改配置自动改写，需要靠自动重试或日志里的重推。

五、能力地图

实际能开哪些类型，以企业开通能力和推送设置里可见分组为准。常见分组如下。

完整类型、建议参数和接收系统见 推送产品 附录。平台后续可能新增类型，接收方不要因为不认识就返回失败，见 系统兼容性。

六、配置项与生效

1. 配置来源与优先级

同一条动作如果既引用了已有目标接口、又填了直配 URL，以目标接口为准。重试如果写了策略对象，以策略对象为准，不再看动作上单独的次数和间隔。

2. 目标接口

配错表现：日志里连接失败、超时、证书错误，或一直打到旧地址。

3. 推送动作

4. 企业接收约定

• 成功：返回 HTTP 200。响应体保持简短，便于日志对照，例如 {"code":0,"message":"success"}。
• 失败：非 200、超时、连接失败都可能触发重试。
• 幂等：同一通话同一类型可能因重试或重推到达多次，用 mainUniqueId / uniqueId + 类型去重。
• 未知类型：解析后忽略即可，不要整单失败。
• 处理时长：业务入库放到异步，先回 200，避免拖过超时。

七、典型业务场景

• 呼入弹屏：来电到达或座席侧响铃回调 CRM，用客户号码和热线号码打开资料。
• 接通写回：来电接通或外呼双方接听后，工单记下座席工号和接通时间。
• 挂机闭环：挂机或主话单回调后更新结果；以话单字段为业务终态，不以回调快慢为准。
• 录音给质检：录音状态推送带录音地址，质检系统再去取文件。
• 座席调度：座席状态变更推到自建监控，和综合状态页对账。

八、上线准备与运营建议

1. 测试租户先做一条来电响铃或挂机，确认企业接口能被公网访问。
2. 参数先带企业编号、通话标识、座席工号、客户号码，再加业务字段。
3. 超时先给到能稳定回 200 的值，再收紧；重试从 1~2 次看起。
4. 生产按系统拆分 URL，不要所有类型打进同一个不好排查的处理函数。
5. 每天看失败量和响应耗时：Webhook 监控看健康，事件回调日志看单条。
6. 推送失败时先对 uniqueId 查话单，再决定要不要重推。

九、与周边能力的关系

十、FAQ

页面保存了，为什么日志没有？
动作未启用、条件不满足、选错类型，或事件还没发生。先打一通测试电话，再按类型和时间查日志。

日志成功了，CRM 里没有记录？
平台只证明 HTTP 被企业接口接收。要在企业侧用通话标识查自己的处理队列和落库。

回调失败，话单会不会丢？
不会。话单独立沉淀。补的是通知，不是重放通话。

和工作台弹屏是一回事吗？
不是。工作台可用 AgentSDK 事件；企业中台用本页 HTTP。部分动作可以两种都推，要分别验收。

能不能靠 Webhook 转接或挂机？
不能。收通知走本页；通话中控制走服务端 SDK 或工作台。

十一、总结

先配可达的目标接口，再按类型启用推送动作，用一通测试电话走完“事件发生 → 日志成功 → 企业落库”。Webhook 解决的是事件怎么通知出去，不替代话单，也不替代通话控制。

附录 A：入口与权限

附录 B：关键字段口径

附录 C：实施检查清单

• 测试环境 URL 公网可达，证书和防火墙已放行平台出口
• 目标接口方法、内容类型与企业接口一致
• 至少一条动作已启用，类型与要测的呼叫一致
• 通话标识、座席工号、客户号码已放入参数
• 企业接口对重复回调幂等，对未知类型不报错
• 测试呼叫后，事件回调日志能看到成功记录
• 人为返回非 200 时，重试次数与间隔符合配置
• 失败样例能用 uniqueId 对上话单
• 生产密钥只开推送管理需要的权限

附录 D：常见问题速查