Polling vs webhooks for long-running media generation

Take the next action at the boundary you actually control

Use the generation-comparison directory when the unresolved choice is MCP, CLI, REST, provider account, or processing boundary. Use the remote-MCP versus local-CLI page when the question is whether an agent or a shell process should own the wait. Use the managed-credits comparison when the decision is account and billing ownership. This page owns only completion signaling and recovery; it does not establish a new OfflineCreator webhook surface.

A webhook receiver becomes part of the security and reliability boundary

fal documents a 15-second timeout for an initial webhook delivery and up to 10 retries over two hours when delivery fails. It tells consumers to make handlers idempotent for repeat deliveries of the same `request_id`. Its verification procedure uses signed headers, the raw request body, a timestamp check, and public keys from a cacheable JWKS. Those details are part of fal's direct webhook contract and must be implemented as documented rather than copied into an OfflineCreator request that has no published callback field.

GitHub's current guidance provides a second provider-specific receiver checklist: use HTTPS, keep sensitive information out of payload URLs, use a high-entropy secret, filter by event and action, return a 2XX response within 10 seconds, process payloads asynchronously, use the delivery identifier against replays, and redeliver missed events after recovery. Those are GitHub recommendations, not fal's signature format or 15-second delivery timeout. For a fal receiver, apply fal's documented raw-body signature and timestamp verification instead.

Authenticate

Verify the provider's exact signature schemePreserve raw body bytes and enforce the documented timestamp or replay window.

Deduplicate

Key processing by request or delivery IDA retry must not duplicate publishing, notifications, billing actions, or downstream jobs.

Recover

Retain a status reconciliation pathA callback can wake work, but a queryable request record is needed when delivery is delayed or missed.

Polling is the current OfflineCreator path; webhooks are an integration pattern, not a documented Studio feature

For the current OfflineCreator MCP and CLI surface, choose bounded polling. The published package documents `generate` with `wait: true`, `get_generation`, and `wait_generation`; it also exposes cancellation, output download, and recent-job tools. The same package does not document a webhook URL argument or callback tool. That absence matters: direct fal.ai webhook support cannot be assumed to pass through OfflineCreator.

Choose a provider webhook only when your application calls a provider surface that explicitly accepts one and you can operate a public HTTPS receiver. fal's current queue documentation supports both status polling and result webhooks. Its status API exposes `IN_QUEUE`, `IN_PROGRESS`, and `COMPLETED`, while a submitted request returns a durable request ID plus status, response, and cancellation URLs. These are fal contracts for direct fal integrations, not undocumented OfflineCreator behavior.

OfflineCreator MCP or CLI

Use the documented wait and status toolsBound the wait, preserve the generation identifier, and resume with a status lookup rather than inventing a callback parameter.

Direct fal queue

Polling and webhooks are both documentedSelect the completion mechanism at submission and keep the request ID as the correlation key.

Decision rule

A provider capability is not automatically a Studio capabilityRequire a published OfflineCreator callback contract before designing Studio automation around webhooks.

Match the completion pattern to the operator and failure budget

Polling fits an interactive agent, CLI command, local script, or modest batch where the caller is already alive and can enforce a deadline. Start the generation, retain its identifier, poll with a capped interval and total wait, and surface a recoverable pending state when the deadline expires. Do not translate “still processing” into failure, and do not poll forever. A recent Atlaris pull request is only one practitioner example, not a benchmark; it added per-request timeouts and backoff after a warning threshold to one long-running generation polling flow.

Webhooks fit detached server automation where completion should wake a workflow without keeping the submitting process open. For direct fal webhooks, the current contract requires signature verification and idempotent handling because failed deliveries can be retried and the same `request_id` can arrive again. GitHub's current guidance independently recommends HTTPS, a webhook secret, quick 2XX acknowledgement, asynchronous payload processing, a unique delivery ID, and redelivery of missed events. A recent PostHog pull request adds a narrower project-specific caution: repeated URL, method, header, and body configuration had become error-prone, while review raised secret-storage and copied-configuration maintenance questions. These are documented controls and individual project findings, not proof that every webhook receiver needs the same architecture.

Choose polling

Interactive or bounded caller-controlled waitsBest when a live client already owns progress, timeout, cancellation, and result retrieval.

Choose webhooks

Detached event-driven server workflowsBest when a durable receiver and background queue already exist and callback operations are acceptable.

Combine them

Webhook for wake-up, status API for truthUse a callback as a signal, then reconcile the authoritative request state by identifier.

Evidence boundary and refresh rule

This draft remains unreviewed. The current OfflineCreator package documents wait and status tools, cancellation, output download, and recent jobs, but no webhook URL argument or callback tool. Direct fal documentation separately supports status polling and result webhooks. These are different published contracts, so do not infer that fal's direct webhook option is available through OfflineCreator.

Three retained practitioner sources do not establish a community consensus or a matched media-generation comparison. The Atlaris pull request is one project's polling implementation, the PostHog pull request is one project's webhook-configuration work, and the Weli essay is one engineer's account of webhook replication work. Each is useful for identifying failure modes, but none supports a universal polling-versus-webhooks winner, a performance benchmark, or a customer-outcome claim.