What is a webhook?
Polling asks "are you done yet?" on repeat. A webhook is the server saying "done" to you exactly once, the moment it finishes.
Definition
A webhook is an HTTP callback: a POST request sent by a server to a URL you specify, triggered by a defined event. Rather than requiring your application to repeatedly check a status endpoint (polling), a webhook delivers a notification to your system the moment an event occurs.
For video generation, the relevant event is a generation job completing (or failing). When the job finishes, the API server sends a POST request to your webhook URL with the job result. Your server receives the notification and processes the completed video.
Why webhooks matter for video generation
Video generation takes seconds to minutes. Polling a status endpoint every second for two minutes produces 120 unnecessary API requests per job. At scale, this wastes compute, consumes rate limit budget, and adds latency (you catch the completion at the next poll interval rather than the moment it occurs).
A webhook delivers the completion event with zero polling overhead. Your application responds to it as it happens. This matters most at scale: a pipeline submitting hundreds of generation jobs simultaneously cannot efficiently poll each one individually.
How webhooks work
Registration: You provide a webhook URL when submitting a generation request, or configure a default webhook URL in your API account settings. This is the endpoint on your server that will receive the notification.
Event delivery: When the generation job completes, the API server sends a POST request to your webhook URL. The request body contains a JSON payload with the job ID, status (succeeded or failed), and (if succeeded) the URL or content of the generated video.
Acknowledgment: Your webhook endpoint returns an HTTP 200 response to acknowledge receipt. If the server receives anything other than a 2xx response, or if the request times out, it retries delivery using exponential backoff.
Payload validation: Reputable API providers include a signature in the webhook request (typically an HMAC of the payload using a shared secret) that you verify before processing. This ensures the request actually came from the API provider and not an attacker who found your webhook URL.
Polling vs. webhooks
For development and simple testing, polling is easier to set up. For production pipelines at any meaningful scale, webhooks are the correct architecture.
Implementing webhooks for LTX-2
The LTX-2 API supports webhook delivery for generation job completion events. Your webhook endpoint must be publicly accessible (or tunnel tools like ngrok can expose a local endpoint during development), return 200 on receipt, and validate the request signature.
For asynchronous video generation pipelines at scale, webhooks are the recommended completion notification mechanism. Full implementation details are in the API documentation.
