Webhook 与事件：内容发布的订阅模型（路线图）

先说清楚现状，再谈路线图：本站内容 API 当前没有 Webhook 推送端点——「内容发布了通知我」这类需求，今天的正确实现是轮询 + 条件请求（成本极低，模板见下文）；Webhook 在路线图的设计清单上，本篇把两件事都写清：现在怎么优雅地轮询、将来的推送会是什么形状。本文属于开发者中心栏目；接口基础先读API 参考总览。

现状：轮询为什么在这里不丢人

「轮询是落后方案」是误读——在三个条件下轮询是正确方案：①事件频率低（内容发布是小时/天级事件，不是毫秒级流）；②读接口有缓存与条件请求支持（本站公开列表带 ETag 与边缘缓存，命中 304 的成本近乎为零）；③订阅方少（一对多的推送基建在订阅方个位数时是负资产）。内容站的事件模型三条全中——所以现状不是「还没做 Webhook」，而是「轮询已经够好，推送是锦上添花」。

轮询的正确姿势：条件请求 + 增量游标

# ① ETag 条件请求（内容没变 → 304，几乎零成本）：
ETAG=$(curl -sI https://axionserve-portal.aeronest-global.workers.dev/api/articles?limit=1 | grep -i etag | tr -d '\r' | cut -d' ' -f2)
curl -s -o /dev/null -w "%{http_code}\n" -H "If-None-Match: $ETAG" https://axionserve-portal.aeronest-global.workers.dev/api/articles?limit=1
#   304 = 无变化；200 = 有更新，拉全量对比
# ② 增量游标（列表接口带 cursor/分页与 published_at 排序）：
#    记录上次最大 published_at，下次只处理更新条目——O(增量) 不是 O(全量)
curl -s "https://axionserve-portal.aeronest-global.workers.dev/api/articles?limit=12" | python3 -c "
import json,sys; d=json.load(sys.stdin)
items=d.get('items') or []
print('最新 published_at:', max((i.get('published_at') or '' for i in items), default='(空)'))"
# ③ 节奏建议：公开列表缓存窗口 15–60s，轮询间隔 ≥60s 就永远不浪费请求；
#    低频场景（内容站监控）5–15 分钟一轮完全够用

为什么先讲轮询的成本账

很多团队对轮询的心理抗拒来自「浪费」的直觉——这个直觉在按请求计费或高频场景成立，在本站场景不成立，算给你看：公开列表端点带 15–60 秒边缘缓存，命中缓存的请求不打数据库（x-axion-d1 响应头的 q=0 可以现场验证）；ETag 命中 304 时响应体为空，一次轮询的流量以百字节计。按 5 分钟一轮全天候轮询算，一天 288 轮、一个月不到九千轮——对带缓存的读接口是轻若鸿毛的负载，对你则是一个 cron 行的维护成本。对比推送方案：你要暴露公网回调端点、实现验签、处理重放与幂等、维护投递监控——基建成本是轮询的百倍，换来的收益只是「快几分钟」。内容发布这种低频事件，几分钟的时延差从来不是业务瓶颈。先轮询，等真实需求把推送的账算正了再迁移——迁移成本也不高，因为订阅逻辑（对比增量、触发通知）两种模式下是同一套。

可订阅的「事件面」：今天就能监听什么

路线图：Webhook 推送的设计清单

推送端点上线时会带着这些设计（先行公开，接受对照监督）：

• 签名验证：每个推送带 HMAC 签名头（secret 建端点时下发）——接收方验签防伪，这是行业标配（各大平台的 webhook 都这么做）；
• 重试与退避：投递失败按指数退避重试（次数上限公开），接收方 5xx/超时不丢事件；
• 幂等键：每个事件带唯一 ID——重试会重复投递，接收方按 ID 去重（这是接收方的义务，我们把它写进文档而不是藏在角落）；
• 事件类型收敛：首批只推内容生命周期事件（published/updated/unpublished）——事件面从窄做起，宁少勿滥；
• 管理面：控制台内建端点管理（增删/启停/投递日志/重放）——没有投递日志的 webhook 系统等于没有。

时间表纪律：不给日期承诺——上线以更新日志的公告为准。在那之前，轮询模板（上文）就是官方推荐方案，它的成本在你的场景里大概率是每月几美分量级。

三类真实订阅者的轮询配方

• 内容镜像/聚合站：监听文章列表端点，节奏 15 分钟一轮 + ETag 条件请求；增量判据用 published_at 游标——一轮命中 304 的成本约等于一次静态请求，全天轮询的流量以 KB 计；
• 行情/价格监控：监听 markets 列表端点，节奏 5 分钟一轮；重点断言「price 从 null 变有值」（基线期指数开始填数的事件）与 updated_at 变化——本站行情缓存窗口 15 秒，轮询快于它就是浪费；
• 社区通知机器人（如 Telegram 群播报新内容）：监听 sitemap 或列表端点，节奏 30–60 分钟一轮；用列表 diff 找新条目，推送文案带原文链接与发布时间——低频事件配低频轮询，机器人和 API 都轻松。

轮询 vs 推送：选择判据

• 事件频率 < 每小时数次：轮询——基建简单、无回调安全面、成本可忽略；
• 秒级响应需求（价格监控、库存联动）：推送才有意义——但先问「真的需要秒级吗」，多数「需要实时」的需求实际容忍 5 分钟；
• 接收方在 NAT 后/无公网端点：只能轮询（推送需要你能被访问）——这也是轮询永不过时的结构性原因。

相关文档：API 参考总览 · Agent 集成 · 更新日志。缓存与条件请求的行为细节以 /docs 调试台实测为准；栏目首页回开发者中心。