SSE vs WebSocket vs webhooks: which to choose#

Use a webhook when you want APITube to push new articles to your server and you do not want to hold a connection open. Use SSE when a long-lived client should receive a one-way stream that reconnects itself. Use WebSocket when you need a two-way socket. All three deliver the same article objects in near real time and bill one credit per article actually delivered — the open connection, heartbeats and pings are free.

The decision comes down to who holds the connection, how reconnection is handled, and which credit pool pays. The rest of this article maps each method to the job it fits, with the exact numbers from the API.

How do the three real-time methods compare?#

Method	Who holds the connection	Reconnection	Credit pool
Webhook	APITube POSTs to your URL — no socket on your side	Automatic retries; 3 consecutive failures disable it	Separate webhook pool
SSE	Your client holds GET /v1/news/stream open	Automatic, via the Last-Event-Id header	Separate streaming pool
WebSocket	Your client holds wss://…/v1/news/ws open	Manual — reconnect with new query params	Separate WebSocket pool

All three accept the same filters as a normal news search (language, category, source, sentiment, entities, sorting, field selection), and all three deliver new articles only — they anchor to the latest matching article and stream what comes after, never a history dump. For backfilling old articles you still run a normal search against /v1/news/everything.

When should I use a webhook?#

Choose a webhook for server-to-server alerting where you do not want to babysit a socket. A background worker checks your active webhooks about every 10 seconds, takes up to 100 articles per delivery, and POSTs them as signed JSON to your URL — so your endpoint only does work when there is something new. Each request carries an X-Webhook-Signature: sha256=… header you verify with your secret. Failed deliveries are retried about every 60 seconds, and after 3 consecutive failures APITube disables the webhook until you re-enable it.

Webhooks are created in the dashboard, not over the API; the API only exposes GET, PATCH and DELETE /v1/webhooks/:id for managing ones that already exist. See what are webhooks and how do they work for the full delivery contract.

When should I use SSE?#

Choose Server-Sent Events for a long-running client that wants the simplest reconnection. Open one connection to GET /v1/news/stream; the server checks for matches about every 30 seconds, sends up to 50 articles per cycle, and keeps the line alive with a heartbeat roughly every 30 seconds. A connection lasts up to 6 hours before you reconnect.

SSE is one-way and resumes itself: every article event carries an id:, and reconnecting with that value in the Last-Event-Id header replays anything you missed. In the browser the native EventSource API does this for you with no extra code, which makes SSE the easiest method to start with. Details and client snippets are in how to stream news in real time with SSE.

When should I use WebSocket?#

Choose WebSocket when you need a two-way socket — for example to send a ping and get a pong back, or because your stack already speaks wss. Connect to wss://api.apitube.io/v1/news/ws; the 50-article batch, 30-second heartbeat and 6-hour maximum match SSE, and WebSocket polls for matches about every 10 seconds. The difference is the transport, not the data.

WebSocket has no Last-Event-Id resume: if the socket drops, you reconnect with your query parameters and resume from the latest article. A missing or invalid key closes the socket immediately with close code 1008. The message format and keep-alive flow are covered in how to stream news over WebSocket.

How does billing differ between them?#

Every method bills per article actually delivered, never per connection — but they draw from different pools, so you can run more than one at once without them competing:

• Webhooks spend a separate webhook credit pool; when it is empty, a positive pay-as-you-go balance is used instead.
• SSE spends a separate streaming credit pool; when it is empty, a positive pay-as-you-go balance is used instead. With no streaming credits and no balance, the connection is rejected with HTTP 402 and code ER0176.
• WebSocket spends its own WebSocket credit pool, again falling back to pay-as-you-go balance, and returns code ER0404 when both are empty.

Concurrent connection limits are the same for SSE and WebSocket. Streaming is not available on the Free plan; paid plans allow 2 connections on Basic, 10 on Professional, and 50 on Corporate. Webhooks hold no socket on your side, so they have no connection limit of this kind.

What if I only need occasional or historical articles?#

If you are not delivering in real time, skip all three and just call /v1/news/everything on demand. A search bills 1 credit only when it returns results — an empty result set costs nothing — and one call returns up to 250 articles. Polling on a timer suits one-off lookups and backfilling history; switch to push delivery (webhook, SSE or WebSocket) only once you need new articles the moment they publish. The official endpoints reference on docs.apitube.io lists every delivery route.

Common Questions#

• Which method is easiest to start with?
• Can I use more than one method at the same time?
• Do all three support the same filters?
• Do test keys work with every method?

Which method is easiest to start with?#

SSE, because the browser EventSource API handles the connection and reconnection for you, and a single cURL command with -N shows live events in your terminal. Webhooks need a public HTTPS endpoint that returns 2xx, and WebSocket needs a wss client, so both take a little more setup than SSE.

Can I use more than one method at the same time?#

Yes. Webhooks bill from a separate webhook pool, SSE from the streaming pool, and WebSocket from the WebSocket pool — three independent pools — so a webhook and a live stream do not draw down the same balance. This lets you, for example, run dashboards over SSE while a webhook alerts a back-end service in parallel.

Do all three support the same filters?#

Yes. Every filter that works on a normal news search works on a webhook, an SSE stream and a WebSocket: append it to the query string (or save it on the webhook). That includes language, category, source, sentiment, entities, sorting and the fl field selector, so you only receive — and only pay for — the articles you actually want.

Do test keys work with every method?#

Yes. A test key delivers live events over all three methods, but the article content is masked for preview and deliveries do not consume your quota. Use a test key to confirm your client connects, parses the article format and handles reconnection, then switch to a live key for full content and real billing.