回调接入

业务后端可以通过 Webhook 接收课堂和课件状态变化。用户在控制台为应用配置 HTTPS 地址并选择事件；事件产生后，课堂服务向该地址发送携带事件数据的 HTTP POST。客户端 SDK 的 onClassInfoChanged 等回调在客户端进程内执行，服务端 Webhook 由业务后端接收。

回调投递流程

左右滑动查看完整图示

业务后端持久化事件后确认接收，再由后台任务处理。超时或非 2xx 响应会触发重试；重复事件按 appId + eventId 去重。

在控制台配置

部署一个可从服务端访问的 HTTPS POST 接口，例如 https://api.example.com/webhooks/eduskit。接口需支持 JSON 请求并保留原始请求体，TLS 证书需有效。
登录控制台，打开「回调配置」，选择需要接收通知的应用。
在「通知地址」填写接口 URL，在「接收事件」中至少选择一项，例如 classroom.started、classroom.ended 和 courseware.ready，点击「保存配置」。
复制本次显示的「签名密钥」，保存到接收服务的密钥配置中。webhookSecret 用于回调验签，与 Server SDK 的 appSecret 分开使用。
在该应用下实际创建、开课或完成一次课件转码，检查接收服务的日志与业务记录。保存配置本身不会触发这些业务事件。

配置按应用生效，一个应用对应一个回调地址和一组订阅。URL 最长 2048 字符。当前控制台和服务端校验接受 HTTP/HTTPS；生产接口使用 HTTPS。

首次设置、更换 URL 或点击「重新生成」都会生成新的签名密钥，明文只在本次返回。只修改订阅事件且 URL 不变时，保留原密钥。更换地址或重新生成后同步更新接收服务的密钥；当前配置只保留一份有效密钥。地址留空并保存会关闭回调并清除密钥。

控制台订阅目录中有部分事件尚未产生通知。实际支持的事件与字段见回调列表。

请求格式

项目	格式
方法	`POST` 到已配置的地址
Content-Type	`application/json`
`x-eduskit-event-id`	与正文 `eventId` 相同
`x-eduskit-event-type`	与正文 `type` 相同
`x-eduskit-timestamp`	本次投递签名的 Unix 秒时间戳
`x-eduskit-signature`	`v1=` 加 64 位十六进制 HMAC-SHA256 摘要

正文示例，ID 与时间均为示例值：

{
  "eventId": "evt_example_created",
  "type": "classroom.created",
  "appId": "app_example",
  "timestamp": "2026-10-09T02:00:00.000Z",
  "data": {
    "classroomId": "cls_example",
    "name": "数学课堂",
    "status": "pending",
    "teacherEduUserId": "eu_teacher",
    "fromStatus": "creating"
  }
}

正文的 timestamp 是事件产生时间，格式为 ISO 8601；请求头时间戳是本次发送时的时间，用于验签时间窗。重试时 eventId 和事件内容保持不变，签名时间戳会重新生成。正文不包含内部 trace 字段。

接收处理

读取原始请求体字节和签名头，使用本应用的 webhookSecret 验签。不要先解析 JSON 再序列化用于验签。
验签成功后解析 JSON，确认 appId 属于当前接收端点，并核对正文的 eventId、type 与请求头一致。
以 (appId, eventId) 建立数据库唯一约束，在同一事务中记录已接收事件和待处理任务。已持久化的重复事件直接返回成功。
持久化成功后返回 200 或 204。耗时业务交给后台任务执行；持久化失败时返回非 2xx，让平台继续投递。

验签算法和 Node.js、Python、Java、Go、PHP 示例见回调验签。这些示例只验证签名和时间窗，业务方仍需实现 HTTP 路由、应用校验、持久化与幂等处理。

事件类型和数据字段可能扩展。接收方可保留未知字段；对于验签通过但业务未处理的事件，记录后确认接收，避免因未实现的业务分支反复重试。

确认、超时与重试

情况	投递行为
接口返回 HTTP 200–299	视为成功，不要求特定响应正文
HTTP 非 2xx、网络错误或请求超时	本轮继续重试
单次 HTTP 请求	超时 10 秒
一轮投递	最多尝试 3 次，包含首次；两次等待分别为 200 ms、400 ms
本轮全部失败	消息重新入队，后续可能再次投递；3 次不是事件的总尝试上限
没有配置地址或未订阅该事件	跳过，不向业务接口投递

事件可能重复或延迟到达，并发投递不保证顺序。接收方使用持久化记录去重，HTTP 成功响应表示事件已接收；后台任务的执行状态由业务系统管理。通过课堂 API查询最新状态，避免旧通知覆盖新状态。关闭地址或取消订阅期间跳过的通知不保证补发。

联调排查

现象	检查项
收不到通知	应用是否一致、地址是否保存、事件是否勾选、事件是否已实际产生、HTTPS 是否可达
验签失败	是否误用 `appSecret`、是否使用了旧密钥、请求体是否被 JSON 中间件或网关改写
时间窗失败	服务器时钟是否同步；使用请求头时间戳，不使用正文事件时间
重复通知	上一次响应是否超时或非 2xx；数据库去重与业务写入是否在同一事务内
开课通知到达但 UI 未就绪	服务端状态变化与客户端 IM、RTC、白板连接是不同阶段

验收时覆盖有效签名、篡改正文、过期签名、重复事件、响应超时和返回 500 的情况。记录 appId、eventId、type、接收时间及响应状态，便于关联投递问题。

回调数据处理

接收方应将用户标识、课堂/课件名称和资源 URL 纳入信息处理清单，限制事件存储的访问范围，清理日志中的敏感字段，并分别确定正文与去重记录的保留期限。见信息采集清单和接入合规。

在控制台配置​

请求格式​

接收处理​

确认、超时与重试​

联调排查​

回调数据处理​