For a CometAPI asynchronous video integration, the completion decision should be stored terminal state—not merely a received callback. CometAPI’s polling and webhooks guide explicitly makes polling the baseline and tells applications to keep it available for missed or provider-specific callback delivery.
That rules out callback-only completion tracking as the default design supported by this guide. Webhooks can add notifications, but callback support and payload shape depend on the selected video endpoint or provider.
A task-ID-centered runbook
- Store the task ID returned at creation. The guide illustrates creation through
/v1/videosand status lookup through/v1/videos/{id}. Add callback fields only when the selected model page documents them; a general video example is not evidence that every endpoint accepts the same callback option. - Keep a polling path independent of callback arrival. For a lost callback, the guide’s recovery instruction is to poll by task ID until the application has stored a terminal state. Receiving an event is not the same stop condition as persisting that state.
- Treat callback bodies as provider-specific input. CometAPI does not define one universal payload for every video model. The guide calls for retaining the raw body, normalizing it in the application, and reconciling final state with polling. Its example
task_id,status, and nested result fields are illustrative—not a schema to impose on all providers. - Make duplicate handling idempotent by task ID. The guide also recommends returning a
2xxresponse quickly and processing the job in the background. A prompt acknowledgement and correct application state handling are separate responsibilities. - Separate terminal-state tracking from result retrieval. A completed response can include
video_url, but that field is optional. Use the selected model’s result fields or/v1/videos/{id}/contentonly where supported; a missing URL alone should not be treated as proof of generation failure.
Signals and escalation
For the application runbook, I would track unresolved task age, the last successful status lookup, callback normalization failures, and whether terminal state has actually been stored. These are proposed application controls, not CometAPI-provided metrics or timeout defaults.
The useful recovery signal is an unresolved task, whether or not a callback arrived. A normalization failure should retain the event for investigation while the polling path remains available. Once terminal state is stored, stop completion-recovery polling for that task; result retrieval can still need separate handling.
Set an application-owned recovery budget and escalation threshold rather than retrying without a bound. If automatic recovery exhausts that budget, leave the task explicitly unresolved and escalate for investigation—do not turn a local timeout into a claimed provider failure or success. The guide does not prescribe a polling interval or retry schedule.
What this guidance does not establish
This is a documentation-based design reading, not a tested reliability assessment. The guide does not establish universal webhook signatures, authentication rules, delivery or ordering guarantees, or cross-model callback equivalence. Those details need endpoint-specific evidence before implementation.
The concrete CometAPI decision is therefore to retain task-ID polling and durable terminal-state tracking even when adding supported callbacks. The notification path can vary by provider; the application’s recovery stop condition should remain explicit.