
Choosing between transcription API webhooks vs polling depends on the provider's contract and your application's infrastructure. Polling asks for job status repeatedly. A webhook delivers a notification to your server when an event occurs. Both require durable job tracking and careful handling of failures.
For ReelWords transcript jobs, use the documented polling workflow. The current public contract provides create, status, and download endpoints. It does not document a transcript-completion callback URL or webhook subscription. The webhook guidance below describes a general integration pattern for providers that support it.
Transcription API webhooks vs polling: choose by workflow
| Question | Polling | Webhooks |
|---|---|---|
| What starts an update? | Your worker requests status | The provider sends an event |
| Do you need an inbound endpoint? | No | Usually an HTTPS receiver |
| Where is the extra traffic? | Repeated status requests | Event deliveries and possible redeliveries |
| What must survive a restart? | Job IDs and next-check scheduling | Received events and processing state |
| What is the main recovery task? | Resume checking unfinished jobs | Reconcile missed or failed delivery |
Start with what the provider actually exposes. An integration designed around an undocumented callback cannot become reliable through retries. For a broader overview of inputs and outputs, see our video transcription API guide.
The ReelWords transcript job lifecycle
The API reference documents these endpoints:
POST /api/v1/transcript-jobscreates a job from a public video URL.GET /api/v1/transcript-jobs/{id}returns its status.GET /api/v1/transcript-jobs/{id}/download?format=txt_timestampsretrieves timestamped text after completion.
Other documented download formats are txt, srt, and vtt. Choose based on the downstream task: prose processing, subtitle interchange, or web playback. Our SRT vs VTT comparison explains the format tradeoffs.
The status values are started, processing, complete, and failed. Match them exactly. Checking for completed instead of complete would leave a finished job waiting indefinitely in your integration.
Keep the API key on your server. The following requests are separate steps in a Bash-compatible shell, not a complete polling program. Set REELWORDS_KEY securely in your environment and replace the example URL with an accessible public video you intend to process.
curl --fail-with-body https://api.reelwords.ai/api/v1/transcript-jobs \
-H "x-api-key: $REELWORDS_KEY" \
-H "Content-Type: application/json" \
--data '{"url":"https://www.youtube.com/watch?v=YOUR_VIDEO_ID","language":"en"}'
After a successful 201 response, persist the returned id. Put that value in JOB_ID and check the same job:
curl --fail-with-body \
-H "x-api-key: $REELWORDS_KEY" \
"https://api.reelwords.ai/api/v1/transcript-jobs/$JOB_ID"
Only after the status is complete, download the result:
curl --fail-with-body \
-H "x-api-key: $REELWORDS_KEY" \
"https://api.reelwords.ai/api/v1/transcript-jobs/$JOB_ID/download?format=txt_timestamps" \
--output transcript.txt
Check the command's exit status before treating the file as a transcript. Error responses must not enter a summarization or publishing pipeline as if they were source text.
Build a polling worker that can recover
Store the provider job ID alongside your own task ID as soon as creation succeeds. Also store the last observed state, last check time, next check time, and any actionable error. A browser tab should not be the only place that knows the work exists.
For each scheduled check:
- Read the persisted job ID and request its status with a request timeout.
- On
startedorprocessing, schedule another check with a bounded delay. - On
complete, enqueue a download or result-processing task once. - On
failed, record the failure details and stop routine polling. - On a transient request failure, reschedule the status check without creating a new job.
Use increasing delays and some random variation when many jobs are active, with a cap chosen for your application's latency needs and the provider's rate limits. If a response supplies Retry-After, respect it. Do not present a sample polling interval as a ReelWords service guarantee.
Set a separate overall monitoring deadline. Reaching it means your application has stopped waiting automatically; it does not prove the provider canceled or failed the job. Preserve the ID so a reconciliation worker or operator can check later.
A timeout is not permission to create another job
A failed status request is normally safe to repeat because it is a read. A timed-out creation request is different: the provider may have accepted it before the response was lost.
The documented ReelWords transcript creation contract does not promise an idempotency-key header. Do not assume that adding one prevents duplicate work. Track submissions in your own system and investigate an ambiguous creation result before blindly repeating the POST.
Similarly, a download failure should lead to another download attempt for the existing completed job, subject to availability and the error returned. Re-transcribing the input is a separate action and may consume additional usage.
| Situation | Integration response |
|---|---|
| Status request times out | Retry the GET with backoff |
| Authentication fails | Stop and repair credentials |
| Creation returns a usage-limit error | Resolve capacity before another submission |
Job reports failed | Inspect the failure details |
Download returns 409 | Recheck whether the job is ready |
| Creation response is lost | Treat acceptance as uncertain |
When a provider offers completion webhooks
Verify the provider's signature using its documented procedure. Persist the event durably, acknowledge within that provider's deadline, and perform lengthy processing in a worker. Deduplicate events and protect downstream side effects from duplicate execution.
GitHub's webhook best practices provide a concrete example of secret validation, asynchronous processing, and tracking delivery identifiers. Its headers and response deadline are GitHub-specific; they are not a contract for transcription services.
Do not assume events arrive once, in order, or with automatic retries. Read the provider's delivery policy. Where an authoritative status endpoint exists, use it to reconcile jobs whose notifications were missed. Webhooks reduce the need for frequent checks; they do not eliminate the need for recovery.
Test failure paths before increasing volume
Exercise the integration with controlled responses before sending a large media batch. Confirm that complete produces one downstream task, failed stops polling, and a network error leaves the same job ID intact. Restart the worker during processing and ensure unfinished jobs resume.
Record request counts and completion-detection delays so you can adjust the polling policy using observed behavior. Keep credentials and full transcript text out of routine logs. For the surrounding architecture, see automating a caption pipeline, while using the API reference for exact ReelWords endpoint behavior.
FAQ
Does ReelWords support transcript-completion webhooks?
The current public transcript API contract does not document them. Use the create, status, and download workflow described here, and check the API reference when planning an integration.
How often should I poll a transcription job?
Choose a bounded schedule based on provider limits, job volume, and acceptable detection delay. Increase the delay while waiting and stop on a terminal state.
Does a polling timeout mean transcription failed?
No. It can mean the request failed or your local waiting deadline elapsed. Retain the job ID and distinguish those cases from an explicit failed status.
Should I retry the create request after every error?
No. Read failures and ambiguous write failures have different consequences. Repeating creation can submit another job unless the provider explicitly guarantees idempotency.
Can this workflow feed a chapter generator?
Yes. Download timestamped text from a completed job, then review the proposed topic boundaries. Our guide to YouTube chapters from a transcript covers the editorial step.
Integrate one complete job first
Prove submission, persistence, status tracking, and a verified download on one recording before adding concurrency. Then exercise failure and recovery paths. This gives you an integration you can inspect when a provider response or network connection behaves unexpectedly.
Explore ReelWords transcription and caption features, compare pricing, and use the API documentation as the source of truth for requests and responses.