# 42｜轮询与 webhook：怎样可靠等待生成结果

媒体生成通常比一次工具调用持续更久。可靠的等待方式要保存任务 ID，让等待进程可恢复，并把本地超时与服务端终态分开。本篇先提供能执行的轮询，再说明 webhook 在系统里的正确边界。

## 最小可执行等待

已有 Node 示例 run 目录与 ID 时，直接查询，不重新提交：

```bash
node examples/node/atlas-media.mjs get --run-dir tutorial-output/node-001
node examples/node/atlas-media.mjs wait --run-dir tutorial-output/node-001 --seconds 120
```

或者使用 CLI 的原 ID：

```bash
PREDICTION_ID='替换为真实已受理任务ID'
atlas generate get "$PREDICTION_ID" --json
atlas generate wait "$PREDICTION_ID" --timeout 10m --json
```

等待上限只限制本地进程。结束时仍在 processing，就记录“仍处理中”；不要转成生成失败，也不要新发一个请求当作延长等待。任务只有实际返回终态时才更新终态。

> 对已受理的 Atlas 任务实现可恢复等待。只查询原 ID，保留账户与任务关系，按有限间隔轮询并设置本地截止时间；401/403 或 ID 不一致时停止，不更换账号。超时记录 pending/unknown，不再次提交。

## 应用里的持久状态

至少保存业务任务 ID、Atlas ID、账户引用、请求摘要、上次检查时间、下一次检查时间和终态。工作进程从队列领取待查询项；同一任务的状态更新使用乐观锁或数据库事务，防止多个 worker 互相覆盖。

对 429、可恢复网络错误和非终态 5xx 使用有上限的退避与适当抖动；收到服务端重试提示时按契约处理。HTTP 5xx 内部可能已经返回 failed 的任务体，不应无限重查该终态。具体限流配额需要实际接口说明，本篇不给一个虚构的“安全 QPS”。

## 未核实 Atlas 回调参数，先不要编造

本次查阅的契约不足以确认可通用使用的 Atlas webhook 注册字段、签名算法与事件投递保证。因此本包没有 `callback_url` 或 `webhook_secret` 的假执行示例，也不把 n8n 的 Wait URL 写成 Atlas 原生回调功能。

如果需要对你的应用发通知，可以由**你自己的查询服务**在确认终态后，将一个内部事件写入数据库/outbox，再投递到你控制的队列或回调接口。事件包含业务任务 ID、已核实状态、事件 ID 和版本，不含 API key。接收方验证你定义的身份与签名，并按事件 ID 去重。这是你的应用协议，不是 Atlas 标准。

## 真有官方 webhook 后仍需核对

上线前必须确认注册入口、签名覆盖字节、时间窗、重投机制、重复与乱序语义。验证事件后仍核对账户/任务归属，必要时读回服务端任务。不要允许某个伪造回调直接把另一个用户任务标成完成，或触发对任意 URL 的带凭据请求。

通知投递采用至少一次时，接收方应幂等处理；“事件发出”“用户收到通知”“生成已完成”“文件保存完毕”仍是不同状态。通知失败重发通知，不重生成媒体。

交付本教程时保留一次从 pending 到终态的实际状态记录，以及超时/重复查询测试。随包测试为模拟接口，不声称已经验证 Atlas 云端 webhook。

## 依据与复现范围

依据：[S3、S6、S9、S10](../SOURCES.md)。本文使用本包约定的教学文件；模型能力与价格以执行时实际目录为准。线上付费步骤未代用户执行，离线验证结果见 [测试报告](../verification/REPORT.md)。通用路径、授权和状态约定见 [执行约定](../common/EXECUTION.md)。
