Guides
Which API should I use?
Velora gives you four ways to get data: REST, the Events API, webhooks and the chat socket. They are not ranked — each one is the right answer for a different shape of program. Start from what you are building, not from the list.
Start from what you are building
Find the row closest to your project. If two rows fit, the one that mentions your deployment shape — browser, desktop, or your own server — is the one to follow.
Messages arrive in order on a live socket, and you reply on the same connection. Polling REST for chat will always be too slow to feel like a bot.
It carries the richest event set — follows, subs, raids, polls, goals, giveaways, sound alerts — and it is the only surface that has them. A browser overlay can hold the socket open with no server of your own.
You get an HTTP POST per event and nothing to keep alive. Read the delivery caveat below before you depend on it — there is no retry.
Live-stream lists, profiles and categories are plain reads. Cache them; do not poll every second.
Events API if something on screen must react instantly; webhooks if your server does the work and a second of delay is fine.
A desktop app can hold a socket open and does not need a public HTTPS endpoint, which webhooks require.
Before you rely on webhooks
Read this before you choose webhooks, not after. It is the one property on this page that can change your architecture.
A webhook is delivered once, and never retried. We POST to your endpoint and wait up to 10 seconds. If your server is down, slow, or returns an error, that event is gone — there is no queue and no redelivery. After 5 failed deliveries the webhook is disabled entirely and you must re-enable it.
If missing an event would be a real problem — payouts, giveaways, anything that owes a user something — do not treat webhooks as your only source. Reconcile against REST on a schedule, or hold an Events API connection and treat the webhook as a nudge rather than the record.
All four, side by side
The same four surfaces, with what each one costs you to run and what it guarantees about delivery.
HTTPS request/response- You need
- Nothing — any HTTP client
- Latency
- As fresh as your last request
- Delivery
- You ask, you get an answer. Nothing is missed because nothing is pushed.
- Best for
- Reading state: who is live, profiles, categories, VODs.
WebSocket (/ws/events) or SSE (GET /api/events/stream)- You need
- A process that stays connected — browser, desktop app or server
- Latency
- Real time
- Delivery
- Live only. Events that fire while you are disconnected are not replayed.
- Best for
- Overlays, alerts, desktop tools — anything on screen that must react now.
We POST to your HTTPS endpoint- You need
- A public HTTPS URL that answers in under 10 seconds
- Latency
- Near real time
- Delivery
- One attempt. No retry. See the caveat below.
- Best for
- Server-side reactions where you do not want to hold a connection open.
WebSocket (/chat)- You need
- A process that stays connected
- Latency
- Real time
- Delivery
- Live only, ordered within a channel.
- Best for
- Reading and sending chat. This is the only surface that can SEND messages.
One trap worth knowing
The Events API and webhooks use different names for some of the same events. A follow is one name on one surface and a different name on the other, so a subscription copied between pages silently never fires.
Same event, two names
channel.followuser.followThe Events API also carries events webhooks do not have at all — polls, goals, giveaways and sound alerts. Check the webhook event reference before assuming an event you saw on one surface exists on the other.
Still not sure? Start with Getting Started — it walks the whole path from account to first working request. Or see what your app can call to check an endpoint is reachable with an OAuth token at all.