事件回调日志

快速阅读

事件回调日志用于回答：

• 平台是否向外部系统发送了事件通知。
• 发送的是哪类事件，关联哪个通话或业务对象。
• 通知发送给了哪个 URL。
• 使用了什么请求方法、参数格式和请求参数。
• 外部系统返回了什么状态码和响应内容。
• 是否成功、是否重试、耗时是否异常。

在现有系统中，事件回调日志的底层能力对应“推送日志”。本文使用“事件回调日志”作为产品归类名称，强调它的审计和对账用途；页面、字段或接口中出现“推送日志”时，可理解为同一类能力的系统命名。

一、文档说明

1.1 文档目的

本文档说明事件回调日志的产品定位、记录内容、查询条件、字段口径、重试与导出能力，帮助客户与外部系统完成事件送达核对和联调排障。

1.2 文档范围

覆盖平台向外部系统发送事件通知形成的日志，包括：

• 来电、外呼、webcall、主叫外呼等通话过程事件。
• 座席状态、按键、录音状态、满意度、预测外呼任务等业务事件。
• 主话单、从话单、队列排队日志、号码操作日志等回调事件。
• HTTP 交互、ASR/RASR、智能体转写等扩展事件。

不覆盖：

• 外部系统收到通知后的内部处理逻辑。
• 外部系统主动调用平台接口形成的 API 请求日志。
• API 请求的调用量统计。
• 工单类独立推送日志，当前管理端推送日志列表会排除工单触发类推送。

二、产品总览

事件回调日志记录平台对外发送事件的请求过程。它证明“平台是否发出通知、通知发给谁、下游如何响应”，适合用于对接联调、送达证明、失败排查和重试复盘。

一句话理解：

事件回调日志看“平台有没有把事件通知出去，外部系统是否正常响应”。

2.1 产品定位

事件回调日志是明细型日志。每一条记录对应一次实际的 HTTP 推送尝试，而不是某类事件的统计结果。

2.2 与推送配置的关系

回调日志中的 URL、请求方法、超时时间、重试次数、延迟推送时间、参数格式等，来自客户在推送配置中的设置或事件本身的推送策略。排查失败时，必须同时核对推送配置、目标 URL 和下游系统日志。

三、入口与接口口径

3.1 管理端入口

管理端提供推送日志查询能力，支持：

• 查询所有可见推送类型。
• 按推送类型、结果、URL、重试次数、通话唯一标识、请求参数、详情、时间范围查询。
• 对失败或需补偿的推送进行重试。
• 导出当前页或按查询条件导出更多数据。

管理端查询时间默认按当天范围补齐，且时间范围不能超过 1 个月。

3.2 开放接口口径

开放接口提供推送日志查询能力：

• 接口用途：查询事件回调/推送日志。
• 请求方式：GET/POST。
• 查询范围：开始时间和结束时间不允许跨月。
• 分页限制：limit 最大不超过 500。
• 常用筛选：推送类型、推送结果、URL、开始时间、结束时间、推送参数、重试次数。

开放接口返回推送类型、唯一标识、URL、请求参数、请求方法、超时时间、重试次数、请求时间、开始时间、结束时间、状态码、响应文本、推送结果、延迟推送时间、参数格式等字段。

四、查询条件

五、字段口径

5.1 页面字段

HOME 字段定义中的推送日志字段包括：

5.2 后端记录字段

后端记录可确认以下字段：

六、事件类型口径

事件回调日志支持的推送类型较多，常见类型包括：

• 通话过程：来电推送、来电响铃、来电接通、来电挂机、外呼响铃、外呼接通、外呼挂机、外呼客户响铃。
• webcall：webcall 响铃、客户侧响铃、客户接听、转接响铃、转接接通、请求回调。
• 座席状态：座席状态推送。
• IVR 与按键：按键推送、IVR 交互结束推送。
• 话单与日志：主通话记录推送、从通话记录推送、号码操作日志、队列排队日志推送、RTC 呼叫日志推送。
• 预测外呼：预测式外呼任务状态、客户响铃、客户接听状态、双方接听、呼叫失败、导入号码失败结果。
• 智能能力：ASR/RASR 语音转换结果、NLU、对话分析、智能体转写结果。

推送类型名称会随版本扩展，验收时应以页面可选类型和客户实际开通能力为准。

七、记录与重试链路

业务事件产生
→ 匹配推送配置和事件类型
→ 生成推送任务并进入执行队列
→ 调用外部系统 URL
→ 记录请求参数、开始/结束时间、状态码、响应内容和结果
→ 失败场景按策略或人工操作触发重试
→ 管理端查询、导出或重推

关键说明：

• 单个业务事件可能产生多条回调日志，例如首次推送失败后发生重试。
• 推送成功通常表示外部系统返回成功响应，不代表外部系统内部业务处理已完成。
• 推送失败需结合 HTTP 状态码、响应文本、超时时间、目标 URL 和下游服务日志判断。

八、导出与重试能力

8.1 导出

管理端推送日志支持 CSV 导出：

• 支持导出当前页。
• 支持按查询条件分批导出全部，系统每批查询 10000 条。
• 全部导出最大处理 100000 条。
• 导出列包括推送类型、唯一标识、URL、请求开始/结束时间、请求参数、请求方法、超时时间、重试次数、排队时间、队列位置、优先级、HTTP 状态码、推送结果和描述。

8.2 重试

管理端支持对推送日志发起重试：

• 查看权限即可进入重试操作。
• 全部重试最多处理 10000 条。
• 重试前同样会按查询条件筛选，并排除工单推送日志。
• 是否允许主动重推还受企业级推送重试配置影响。

九、典型业务场景

9.1 下游系统未收到事件

确认事件类型、业务对象和时间窗口
→ 查询事件回调日志
→ 核对 URL、唯一标识、请求参数和推送结果
→ 查看状态码、响应内容和重试次数
→ 与下游系统接收日志对账

9.2 推送失败集中排查

筛选失败结果
→ 按 URL 或推送类型聚焦范围
→ 查看状态码和响应文本
→ 核对推送配置、目标服务状态、网络和超时时间
→ 必要时发起重试

9.3 通话事件与话单联查

通话类推送日志可通过 uniqueId 或推送参数中的 mainUniqueId 与话单、队列日志、外呼失败日志等联查。联查时应注意：

• 同一主通话可能包含主话单、从话单和多个状态事件。
• 某些座席状态推送的日志字段 uniqueId 可能为空，但参数中可能带有通话标识。
• 回调时间不一定等同于通话开始或结束时间，应以话单时间为业务事实口径。

十、与周边能力的关系

十一、权限与安全建议

已确认的管理端权限包括：

• 查看权限：用于查看推送日志和可选推送类型。
• 导出权限：用于导出推送日志。

建议：

• 重试能力仅开放给实施顾问、系统管理员或经授权技术人员。
• 导出权限单独控制，避免将请求参数和响应内容过度扩散。
• 对号码、客户信息、请求参数和响应文本进行脱敏或按最小必要原则展示。

十二、验收口径

上线或联调时建议验证：

• 成功回调可以在日志中查到。
• 失败、超时或异常响应可以在日志中查到。
• URL、请求参数、状态码、响应内容、重试次数可用于下游对账。
• 通话类事件可通过 uniqueId 或参数中的 mainUniqueId 联查话单。
• 当前页导出、全部导出、重试权限符合客户要求。

十三、FAQ

Q1：事件回调日志为什么页面上叫推送日志？
因为系统底层能力以“推送”命名。产品归类中把它放在事件回调日志下，是为了突出平台对外通知和对账审计的用途。

Q2：回调成功是否代表下游业务处理成功？
不一定。回调成功通常表示外部系统返回成功响应，后续业务处理仍需下游系统确认。

Q3：同一个事件为什么有多条日志？
可能是多种事件分别推送，也可能是同一事件发生失败重试。

Q4：回调日志能替代话单吗？
不能。回调日志证明通知动作，话单证明通话事实和结果。

十四、总结

事件回调日志是平台对外事件通知的关键对账能力。它基于现有推送日志能力，记录事件类型、目标 URL、请求参数、请求时间、响应状态、推送结果和重试情况，适合用于联调、送达证明和失败排查。