Should I wait for a FiveAPI webhook or poll the task id?

Short answer: Prefer a signed webhook. FiveAPI calls your HTTPS endpoint when a video task reaches a terminal status, and you can still poll GET /v1/tasks/{task_id} if a delivery is delayed.

This note is for backend engineers wiring an async video job into an existing queue, not for a browser demo.

What you receive

Webhooks are the documented preferred path. You can set a default endpoint for the account in the console, or pass webhook_url on the create request to override it for that task. Endpoints must be public HTTPS.

FiveAPI sends a signed POST with the full task object for:

• task.completed — the MP4 is ready; credits.charged is final; download data.output.video.url (it expires in 7 days).
• task.failed — the credit hold was released; read data.error and resubmit only if retryable is true.
• task.cancelled — the hold was released; update your records.

The console lets you copy or rotate the signing secret, send a signed test event, and inspect delivery attempts. Verify the signature before you trust the body. Deliveries are retried automatically if your endpoint is down.

When polling still helps

Polling every few seconds is the fallback for debugging, for a worker that started before the webhook was configured, or for reconciling a missed event. Do not poll in a tight loop, and do not treat a queued status as a failure. Store the task id as soon as the create call returns.

Short Q&A

Can I put the API key in the webhook handler running in a browser? No. Keep keys on the server. They are shown once and should live in FIVEAPI_API_KEY.

Is webhook setup available immediately after signup? Only after the account can use the console as an approved production account. New production accounts are reviewed before they can create API keys.

— fiveapi.ai notes, 2026-11-13