Webhook vs polling for video processing status

For async video processing, a webhook beats polling. Encoding takes anywhere from a few seconds to several minutes, and if you poll a status endpoint on a timer you’re either burning requests while nothing has changed or finding out late that it has. A webhook is push: rehelios calls your endpoint the moment a video’s state changes, so you find out immediately, with zero wasted calls.

The async problem: encoding is not instant

Uploading a video and getting back a playable URL in the same request would be nice, but it doesn’t reflect how encoding works. A file lands, gets probed, gets transcoded into an adaptive HLS (and optionally DASH) ladder across several renditions, and captions get generated — none of that finishes in the time an HTTP request is willing to stay open. A ten-second clip might be ready in a few seconds; a ninety-minute lecture recording can take minutes. Your API call to create the video has to return before any of that work is done.

So every video platform, rehelios included, splits this into two steps: the request that starts processing, and a separate signal for when it’s done. video.status starts at processing and moves to ready or failed. The question is how your code finds out when that happens.

Polling: ask until the answer changes

The obvious approach is a loop: call GET /v1/videos/{id} every few seconds and check status. It works, and it requires no infrastructure on your side — no public endpoint, no signature verification, nothing to expose to the internet. That simplicity is real, but it comes with real costs:

• Wasted requests. If a video takes ninety seconds to encode and you poll every five seconds, that’s eighteen calls to learn one bit of information: done or not done. Multiply by every video your app processes and most of your API traffic is you asking “yet?” and getting “no.”
• Rate limits. Poll aggressively across hundreds of concurrent uploads and you’re competing with your own application traffic for the same rate-limit budget — for a signal that a webhook delivers for free.
• Latency between ready and detected. Poll every ten seconds and your best case is instant, your worst case is a ten-second lag before you even notice the video is ready, on top of encoding time your user is already waiting on.
• Backoff complexity you have to write yourself. Poll too tight and you risk rate limits; too loose and you add latency. So you end up building exponential backoff, jitter, and a cutoff for videos that never finish — solving a scheduling problem that doesn’t need to exist.

None of this is hard, exactly. It’s just work spent building a queue-check loop instead of shipping the feature that depends on the video being ready.

Webhooks: the platform tells you

A webhook flips the direction. Instead of you asking rehelios, rehelios tells you: the moment a video’s state changes, we send an HTTP POST to the endpoint you configured, with an event type (video.ready, video.failed, caption.ready) and the relevant payload. There’s no interval to tune and no gap between “actually ready” and “you find out” beyond normal network latency. You get one request per state change, not N requests hoping one of them lands after the change. For a platform processing many videos concurrently, that’s the difference between traffic proportional to the number of events and traffic proportional to the number of events times however aggressively you’re willing to poll.

Doing webhooks right

A webhook endpoint is a public URL, which means you have to treat it like one:

• Verify the HMAC signature on every request. rehelios signs each webhook payload with a secret only you and rehelios know; recompute the HMAC over the raw body and compare it to the signature header before trusting anything in the payload. Skip this and anyone who finds your endpoint can POST a fake video.ready event at you.
• Return a 2xx fast, then process async. Your handler’s job is to acknowledge receipt, not to finish the work. Verify, enqueue, respond. If your webhook does the real work (updating a database, kicking off a downstream job, notifying a user) inline before responding, a slow dependency turns into a slow — or dropped — webhook.
• Expect retries, so handlers must be idempotent. Delivery is at-least-once, not exactly-once: network blips, timeouts, or a 5xx from your endpoint will make rehelios retry. Key your handling off the event ID (or video ID plus status) so processing the same event twice is a no-op, not a duplicate side effect.
• Keep a polling fallback for missed events. Webhooks handle the common case; they don’t guarantee the impossible. If your endpoint is down for an extended window, a periodic reconciliation job (poll videos still processing past some threshold) catches anything a webhook didn’t get through. Cheap insurance for a rare failure mode.

POST /webhooks/rehelios
  1. read raw body + signature header
  2. verify HMAC(secret, raw_body) == signature   -> 401 if not
  3. respond 200 immediately
  4. enqueue { event_id, type, video_id, payload } for a worker
     -> worker looks up event_id, skips if already processed

Why this matters for automation and AI agents

The same property that makes webhooks better for your backend — they’re push, not poll — is what makes an API drivable by automation in the first place. An agent that kicks off an upload and then has to sit in a loop calling a status endpoint is spending its turns on busy-waiting instead of doing anything useful. An agent that registers a webhook (or reacts to one relayed through your own system) can fire the upload and move on to the next task, resuming only when there’s actually something to act on. Event-driven APIs compose; poll-driven ones force every caller, human or agent, to reinvent the same waiting loop. See /agents and /mcp for how rehelios exposes this to agent runtimes directly, and giving an agent video upload and hosting for the fuller picture. The full webhook event reference and signature details are in the docs.