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 調試臺實測爲準；欄目首頁回開發者中心。