Real-time news API: webhooks, streaming and polling
There are three ways to consume a news API in “real time,” and they are not equal. Polling is simple but slow and wasteful; webhooks and streaming push events to you the moment they land. Here's when to use each, with working examples.
Polling: simplest, but the worst latency
You ask the API for recent items on a timer. It's easy to build, but you pay for it twice: latency (you only see news at the next tick) and quota (most calls return nothing new). It's fine for a dashboard that refreshes every few minutes, not for alerting.
curl -H "X-API-Key: YOUR_KEY" \ "https://api.newsagentdata.com/v1/breaking?min_score=7&days=1"
Every record already carries urgency, political_lean, country_tags, topic_tags and a cluster_id — so even polling gives you ranked, labelled data, not raw headlines.
Webhooks: push, filtered, HMAC-signed
Register a URL and the API POSTs matching high-urgency items to you within roughly 60 seconds of ingestion — no loop, no wasted calls. Filter the subscription so you only get your news:
POST /v1/webhook?url=https://your.app/hook&min_score=7&country=ua&topic=defense
Payloads are HMAC-signed so you can verify they came from us. This is the right default for alerting, Slack/Telegram bots, and pipelines that react to events.
SSE streaming: one long-lived connection
If you'd rather hold an open connection than run a public endpoint, subscribe to the Server-Sent Events stream. The same scored, classified events arrive on a single socket — ideal for a live dashboard or an in-process consumer.
curl -N -H "X-API-Key: YOUR_KEY" \ "https://api.newsagentdata.com/v1/stream?min_score=7"
Which should you use?
- Alerting / bots / pipelines → webhooks (filtered, signed, no polling).
- Live dashboards / in-process consumers → SSE stream.
- Periodic snapshots / batch → polling
/v1/breakingor/v1/feed.
Whichever you pick, de-duplicate by cluster_id so one event doesn't page you forty times. See the API docs for every parameter, and the breaking-news guide for a full pipeline.