EventHub
火山引擎 Saas 直播回调
火山引擎 SaaS 直播回调转发接入说明
火山引擎 Saas 直播回调转发到 EventHub 接入说明
本文档面向第三方客户，适用于以下场景：
- 你已经在火山引擎直播控制台配置了回调地址
- 你希望先由自己的业务服务接收火山引擎 Saas 直播回调
- 你的服务在保留火山原始回调的基础上，补充一个
eventhub对象，再转发到 EventHub
本文档覆盖的回调类型包括但不限于：
- 推流开始
- 推流结束
- 录制完成
- 截图
- 其他火山直播回调事件
核心原则：第三方客户收到火山引擎 Saas 直播回调后，应尽量完整保留原始回调内容，并直接在原始对象基础上增加一个
eventhub扩展对象，再转发给 EventHub。
1. 接入总览
推荐链路如下：
火山引擎 Saas 直播
-> 你的回调接收服务
-> 在原始回调对象上补齐 eventhub
-> 转发到 EventHubEventHub 对外接收地址为：
| 项目 | 值 |
|---|---|
| 生产 Base URL | https://eh.citv.cc |
| 完整地址 | https://eh.citv.cc/event/volc/saas/live/{appid} |
| 请求方法 | POST |
| Content-Type | application/json |
其中：
{appid}由 EventHub 分配- EventHub 会根据
{appid}找到对应的应用配置，并使用该应用的secret校验签名
2. 你需要做什么
第三方客户侧需要完成 4 件事：
- 接收火山引擎 Saas 直播原始回调
- 尽量原样保留火山引擎 Saas 直播回调内容，不要重新包装为其他根结构
- 在原始回调对象上增加
eventhub字段，补充业务信息 - 使用 EventHub 分配的
AppSecret透传或重算签名，然后转发到 EventHub
3. EventHub 请求格式
请求体就是：
- 根对象：火山引擎原始回调对象
- 扩展对象：
eventhub
也就是说，转发给 EventHub 的 JSON 结构应该是：
{
"...火山原始回调字段...": "...",
"eventhub": {
"...第三方客户补充的业务字段...": "..."
}
}eventhub 示例：
{
"eventhub": {
"title": "直播活动",
"type": 1,
"ccid": "83633_394",
"domains": ["<商户子域名>.<平台子域名>.citv.cn"],
"pageUrl": "https://<终端用户页面地址>",
"auditUrl": "http://<审核页面地址>",
"auditors": ["ai"],
"startTime": 1774510939000,
"endTime": 1774510940000,
"pushEndReason": "normal",
"views": 26,
"providers": [
{
"type": "live",
"serviceId": "sPq1qe1riZ",
"contentId": "83633_394_h5_mix"
}
]
}
}3.1 eventhub 字段说明
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
title | string | 是 | 内容标题，如直播间名称、视频标题等 |
type | number | 是 | 业务侧内容类型标识，推荐枚举值：1 = 直播2 = 点播3 = 伪直播（VodToLive） |
ccid | string | 是 | 业务侧内容唯一标识，用于关联业务系统中的内容记录 |
domains | string[] | 是 | 该内容关联的完整域名列表，用于多域名场景下的路由识别 |
pageUrl | string | 是 | 终端用户可访问的直播间或视频详情页地址 |
auditUrl | string | 是 | 审核员访问的审核页面地址，用于内容审核场景 |
auditors | string[] | 是 | 审核员 ID 列表，标识负责该内容审核的人员，如 ["ai"] |
startTime | number | 是 | 直播/内容开始时间，13 位毫秒级时间戳 |
endTime | number | 是 | 直播/内容结束时间，13 位毫秒级时间戳 |
views | number | 可选 | 当前内容的实时访问量/观看人数 |
pushEndReason | string | 否 | 推流结束时需要，结束原因，枚举值：normal（正常结束）、block（封禁）、unknown（未知） |
providers | object[] | 是 | 云服务商信息列表，标识该内容在第三方云服务的配置 |
providers[].type | string | 是 | 服务类型，常见值为 live（直播）或 media（媒体） |
providers[].serviceId | string | 是 | 云服务控制台中的服务/应用 ID |
providers[].contentId | string | 是 | 火山引擎 Saas 化直播专属，客户方调用注册商户接口时候颁发的 contentId，由 CITV 颁发 |
4. 火山原始字段说明
转发时，根对象建议直接使用你从火山收到的原始 JSON 对象，不要丢字段，不要只挑少数字段。
推荐做法：
- 火山引擎 Saas 直播回调里原本有哪些字段，就尽量完整保留哪些字段
- 原始字段仍放在根对象，不要挪到
eventhub中 - 对于推流开始、推流结束、录制、截图等不同回调类型，都使用同一套协议