Event-Driven Video Pipelines with AIOZ Stream Webhooks

Polling an API every few seconds to check if a video finished encoding works, and it's a genuinely worse way to build a pipeline than the alternative: AIOZ Stream can push a notification to your own server the instant something happens instead. Five real events cover the whole encoding lifecycle. One real gap is worth knowing about before wiring a production pipeline around them.

TL;DR:

• AIOZ Stream fires five documented webhook events: file_received, encoding_started, encoding_finished, encoding_failed, and partial_finished (one quality tier done, not the whole ladder).
• Registering a webhook is one POST to /api/webhooks with a target URL, an optional name, and boolean toggles per event, not a separate subscription per event type.
• AIOZ's documentation doesn't specify a payload structure for any event, and doesn't describe a signature or secret verification mechanism, worth planning around rather than assuming either exists.
• That's a real security gap, not a nitpick: without signature verification, anything that can reach your webhook URL can send a fake "encoding finished" event and trigger whatever your pipeline does next.
• The practical mitigation until AIOZ documents something better: treat a webhook as a hint to go check, not a fact to act on directly, confirm the underlying video's actual status via a real API call before triggering anything consequential.

Why event-driven beats polling

A polling loop checking encode status every few seconds wastes requests on every check that returns "still processing," and it adds latency equal to however long the poll interval is between the actual finish and your pipeline noticing. A webhook flips that: AIOZ Stream's own servers push a notification the moment the state actually changes, no wasted requests, no polling-interval lag at all. That matters most for chaining steps together, transcoding finishes, then captioning starts, then a CMS gets notified, then a publish job runs, each step reacting to a real event instead of a process babysitting a status field on a timer.

The five real events AIOZ Stream fires

Registration is a single POST to /api/webhooks with a url (required, the endpoint AIOZ will send notifications to) and an optional name, defaulting to "default-name-webhook" if left out. Event subscription isn't a separate call per event type, the same registration request carries boolean toggles for each of the five documented events: file_received fires once a video file finishes uploading, encoding_started when transcoding actually begins, encoding_finished once the whole job completes, encoding_failed if it doesn't, and partial_finished, the one worth building around specifically, fires once per individual quality tier in the ladder as each one finishes, not just once at the very end. That last one is what makes a progressive-availability pipeline possible: a 1080p rendition can go live the moment its own tier finishes encoding, without waiting for a 4K tier further up the ladder to also complete.

Chaining events into a real pipeline

A practical chain: file_received triggers a status update in your own UI, "processing," so a user isn't staring at nothing. encoding_started is mostly a logging/monitoring event, confirmation the job actually picked up rather than silently stalling in a queue. partial_finished is where the real automation lives, each firing can trigger a check of whether a specific rendition, say the lowest tier for fast initial availability, is ready to reference in a player before the rest of the ladder finishes. encoding_finished is the signal to run whatever depends on the complete ladder, triggering a CMS update, a publish step, a notification to the uploader. encoding_failed should route to alerting and, depending on the failure, a retry, not silently vanish into a log nobody watches. None of these events are documented as retried automatically by AIOZ, which makes an idempotent handler, safe to process the same event twice without duplicating downstream work, a reasonable default assumption rather than something to verify after a production incident. The standard, low-effort way to get there: store the identifying details of each processed event, a video ID plus event type is enough without a dedicated event ID field being documented, in a database, and check that record before acting on a new incoming event rather than trusting that AIOZ's delivery is exactly-once. That single check is what stands between a network hiccup causing a retried delivery and a video accidentally getting published, or re-encoded, twice.

The real security gap: no documented signature verification

This is worth being direct about. AIOZ's webhook documentation doesn't describe a signing secret, an HMAC signature header, or any mechanism for confirming an incoming request actually originated from AIOZ Stream rather than from anyone who discovered the webhook URL. Compare that to how a mature webhook system handles it: Stripe signs every webhook with an HMAC-SHA256 signature in a Stripe-Signature header, computed from a secret only Stripe and the receiving server know, plus a timestamp specifically to prevent replay attacks, an intercepted, retransmitted payload gets rejected once its timestamp falls outside a tolerance window. Stripe's own documentation states the stakes plainly: without verification, "an attacker could send fake webhook events to your endpoint to trigger actions like fulfilling orders, granting account access, or modifying records." The same class of risk applies to a video pipeline, a forged encoding_finished event could trigger a premature publish, a forged encoding_failed could trigger an unnecessary and costly re-encode. Until AIOZ documents a comparable mechanism, the safer default is treating an incoming webhook as a prompt to verify, not a fact to act on: call back to AIOZ's own API to confirm the referenced video's actual current status before triggering anything that can't be easily undone, rather than trusting the webhook payload's claim at face value. IP allowlisting, the second layer Stripe recommends alongside signature verification, isn't confirmed as an option here either, no published list of AIOZ's sending IP addresses for webhook deliveries turned up in the documentation searched for this article, which leaves the confirm-before-acting pattern as the more reliable mitigation to build around rather than assuming a second layer of defense exists unconfirmed.

What isn't documented: payload structure

AIOZ's webhook reference describes the five event names and the registration mechanics, but doesn't publish an example payload for any of them, no sample JSON body showing what fields actually arrive at your endpoint when, say, partial_finished fires. A reasonable expectation is that it at least identifies the video and the specific quality tier involved, but that's an inference from the event's purpose, not a documented contract. Sending a real test video through a registered webhook and logging the raw payload before building parsing logic around an assumption is the safer path here, the same "verify directly rather than assume" habit this series has applied to AIOZ's other undocumented corners. Concretely, that means standing up even a throwaway endpoint, a serverless function that just logs the raw request body is enough, registering it against a real test video, and reading the actual JSON that arrives for each of the five events before writing a single line of parsing logic against a guessed schema. That first real payload is worth keeping on hand afterward too, a concrete fixture to test the handler against later rather than relying only on live traffic to catch a schema assumption that turned out wrong.

Frequently Asked Questions

What events does AIOZ Stream's webhook system support?
Five: file_received, encoding_started, encoding_finished, encoding_failed, and partial_finished, which fires once per individual quality tier rather than once for the whole job.

Do I need a separate webhook registration for each event type?
No. One registration call to /api/webhooks carries boolean toggles for all five events at once.

Does AIOZ Stream sign its webhook payloads for verification?
Not documented. There's no described signing secret or signature header, unlike mature systems such as Stripe's HMAC-based Stripe-Signature header.

How should I protect a pipeline against a forged webhook event?
Treat the webhook as a prompt to check, not a fact to trust. Call AIOZ's API to confirm the referenced video's actual status before triggering anything consequential, rather than acting directly on the payload's claim.

What's special about the partial_finished event?
It fires once per quality tier as each one completes, not just once at the end, enabling a rendition to go live as soon as its own tier is ready instead of waiting for the entire ladder to finish.

Is there a documented payload format for webhook events?
No. AIOZ's docs name the events and describe registration, but don't publish an example payload; logging a real event before building parsing logic is the safer approach.

Related Reading

• Import Existing HLS Video Without Re-Encoding: the same encoding.started/finished/failed events reused to track an import's progress
• Building a Video Analytics Dashboard: pairing webhook-driven encoding status with polled watch-time and retention data on one dashboard
• Handling API Rate Limits in Production: an event-driven alternative to polling that sidesteps the read-limit pressure entirely
• AIOZ Stream Developer Guide: the full API surface this webhook system is part of
• Chunked Video Upload Tutorial: 50-200MB Parts Explained: the upload flow that eventually triggers file_received
• Getting Started with the AIOZ Stream Node.js SDK: the client library alternative to raw webhook handling
• How to Build a Video Bitrate Ladder: A Practical Guide: the per-tier ladder structure partial_finished fires against
• AIOZ Stream API Keys: the credential scope a webhook-triggered status check should use

References

• AIOZ Stream Webhooks API documentation: the five events, registration endpoint, and fields cited above
• Stripe: Webhooks: the HMAC-SHA256 signature verification and replay-attack protection cited above as a comparison point
• Hookdeck: How to Implement Webhook Idempotency: the event-ID deduplication pattern cited above