流媒体与实时通信 / 系统课时
流状态 Webhook 如何保证幂等处理
流状态 Webhook 如何保证幂等处理
直播平台的 Webhook 可能重复投递、延迟到达,甚至出现“断开”晚于“重新推流”的乱序事件。本篇给出一套可直接落地的规则:用 eventId 去重,用 sessionGeneration 区分重连代次,用 stateVersion 决定同一代次内的新旧状态,并让失败重试保持原事件不变。
学习目标
- 能设计包含
eventId、会话代次和状态版本的流状态回调载荷。 - 能判断重复、乱序、跨重连事件,避免旧事件覆盖新状态。
- 能实现失败重试与幂等消费,并用明确的状态转移规则验收。
先把事件身份设计完整
一条 Webhook 至少要有四个能支撑幂等判断的字段:eventId 标识一次通知,streamId 标识直播流,sessionGeneration 标识第几次推流会话,stateVersion 标识该会话内的状态版本。occurredAt 用于审计和排障,但不要单独拿它判断新旧,因为跨机器时钟可能有偏差。

推荐载荷可以固定成下面的结构,生产环境再按需要增加租户、签名和资源版本字段。
{
"eventId": "evt_01HWEBHOOK42",
"eventType": "stream.started",
"streamId": "room-1001-main",
"sessionGeneration": 42,
"stateVersion": 1,
"occurredAt": "2026-10-25T10:30:00Z",
"payload": {
"publisherId": "publisher-7"
}
}预期结果
eventId 唯一标识这次投递;同一通知重试时不改变它。
sessionGeneration=42 表示第 42 次推流会话。
stateVersion=1 表示该会话的第一个状态版本。用代次和版本处理乱序
假设当前数据库中的状态是 generation=41, version=9, state=ended。下一次主播重新推流,服务端必须产生 generation=42, version=1, state=started。此后即使旧会话的 generation=41, version=10 迟到,也只能判为过期,不能把当前状态改回旧会话。
同一代次内只比较 stateVersion。例如先收到 disconnected(version=8),后收到 ended(version=7),后者不能覆盖前者;反过来先收到 ended(version=7),再收到 disconnected(version=8),则可以接受后到事件,但业务状态是否允许从终态回到断开态,应由状态机规则拒绝,而不是靠时间戳猜测。
可以把接受条件固定成:
sessionGeneration小于当前代次:拒绝更新。- 代次更高:建立新会话状态,并把版本从该事件开始记录。
- 代次相同且
stateVersion小于或等于当前版本:拒绝更新。 - 代次和版本都更新:进入状态机校验,通过后写入。
对于 stream.ended 这种终态,建议在同一代次内禁止任何更小或相等版本的状态覆盖;重新开始推流必须使用新的 sessionGeneration。
让重复投递真正幂等
幂等不能只靠“更新数据库时再判断一次”。更稳妥的做法是把 eventId 建唯一键,并在状态更新与事件落库之间使用同一事务或等价的一致性边界。这样同一事件并发到达两次时,最多只有一个消费者完成业务写入,另一个得到“已处理”结果。
下面这个纯 Node.js 示例用内存结构模拟生产环境中的两个存储:processedEvents 相当于幂等表,streams 相当于流状态表。代码不依赖第三方包,可直接用 Node.js 20+ 运行。
const processedEvents = new Set();
const streams = new Map();
function consumeWebhook(event) {
// eventId 是一次通知的稳定身份,重试必须保持不变。
if (processedEvents.has(event.eventId)) {
return { action: "duplicate", state: streams.get(event.streamId) ?? null };
}
const current = streams.get(event.streamId);
if (
current &&
(event.sessionGeneration < current.sessionGeneration ||
(event.sessionGeneration === current.sessionGeneration &&
event.stateVersion <= current.stateVersion))
) {
processedEvents.add(event.eventId);
return { action: "stale", state: current };
}
const next = {
state: event.eventType,
sessionGeneration: event.sessionGeneration,
stateVersion: event.stateVersion
};
// 真实数据库中应把事件去重记录和状态更新放在同一事务边界。
streams.set(event.streamId, next);
processedEvents.add(event.eventId);
return { action: "updated", state: next };
}
const first = consumeWebhook({
eventId: "evt-1",
eventType: "stream.started",
streamId: "room-1001-main",
sessionGeneration: 42,
stateVersion: 1
});
const retry = consumeWebhook({
eventId: "evt-1",
eventType: "stream.started",
streamId: "room-1001-main",
sessionGeneration: 42,
stateVersion: 1
});
const lateOldSession = consumeWebhook({
eventId: "evt-2",
eventType: "stream.ended",
streamId: "room-1001-main",
sessionGeneration: 41,
stateVersion: 10
});
console.log(JSON.stringify({ first, retry, lateOldSession }, null, 2));预期输出
{
"first": {
"action": "updated",
"state": {
"state": "stream.started",
"sessionGeneration": 42,
"stateVersion": 1
}
},
"retry": {
"action": "duplicate",
"state": {
"state": "stream.started",
"sessionGeneration": 42,
"stateVersion": 1
}
},
"lateOldSession": {
"action": "stale",
"state": {
"state": "stream.started",
"sessionGeneration": 42,
"stateVersion": 1
}
}
}这个示例的关键不是 Set 本身,而是判断顺序:先判重复事件,再判代次和版本,最后才执行状态写入。生产环境中可把 processedEvents 换成数据库唯一索引、Redis SET NX 或带唯一约束的事件表,但仍要保证“去重成功”和“业务状态更新”不会长期处于彼此不一致的状态。
重试策略要保证语义不变
Webhook 接收端不应把“已经收到”与“已经处理成功”混为一谈。只有完成幂等校验、状态写入及必要的事件落库后再返回成功;处理异常时返回非 2xx,让发送方按退避策略重试。重试事件必须复用原来的 eventId、sessionGeneration 和 stateVersion,不能每重试一次就生成一个新的事件身份。
一个实用的重试序列可以是 1s、2s、4s、8s、16s,并设置最大重试次数与死信存储。若服务连续失败,死信记录至少保留 eventId、原始载荷、首次失败时间和最后失败原因,方便人工或后台任务重新投递。
验收时检查四种情况
上线前至少构造以下四组测试,每组都要检查最终流状态,而不只看 HTTP 返回码。
| 测试场景 | 输入顺序 | 预期业务结果 |
|---|---|---|
| 正常开始 | started g42 v1 | 状态变为 started |
| 重复通知 | started g42 v1、再次收到同一 eventId | 只写一次,第二次 duplicate |
| 同代乱序 | ended g42 v7、disconnected g42 v6 | 最终保持 ended 或按业务状态机拒绝非法回退 |
| 跨代迟到 | started g42 v1、ended g41 v10 | 最终保持 g42,不被旧会话覆盖 |
最后特别检查一个容易漏掉的边界:主播快速断开后重新推流时,旧会话的迟到事件必须能够被识别为旧代次;否则“流已恢复”之后又被一条旧的 ended 覆盖,直播间就会出现错误的离线状态。