Webhooks vs. Polling for YouTube Transcripts

Use a webhook (or callback_url) when you want to know the instant a batch finishes without burning request budget. Use polling when the integration is a one-off script, a cron job, or you can't expose a public endpoint. Both read from the same batch state — this is a tradeoff of latency and complexity, not correctness.

The deeper reason this choice exists: POST /api/v1/transcripts/resolve already answers most requests synchronously, since cache hits come back inline in the same response. Webhooks and polling both exist for the remainder — videos Scriptube didn't already have — where there's genuinely a job running in the background and something has to find out when it's done.

Polling

Submit, then call GET /api/v1/transcripts/{batch_id} until status stops being queued/processing:

while True:
    status = requests.get(f"{BASE}/api/v1/transcripts/{batch_id}", headers=HEADERS).json()["status"]
    if status in ("completed", "failed", "partial", "cancelled"):
        break
    time.sleep(5)

Good for: scripts that run once and exit, cron jobs, local testing, anything that can't receive inbound HTTP. Downside: reads are capped at 60 requests/minute per key, so tight loops across many concurrent batches add up, and you're always a few seconds behind the actual completion time.

The math that matters: if you're polling N batches at once every 5 seconds, that's N × 12 read requests per minute against the 60/minute cap — fine for a handful of batches, a problem past roughly 5 concurrent ones on the same key. Back off the poll interval as batches run longer, or switch to a webhook once you're past a few concurrent jobs.

Registered webhooks

Register once, get push notifications for every batch going forward:

curl -s -X POST https://scriptube.me/api/webhooks/register \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"url": "https://yourapp.example.com/hooks", "events": ["batch.completed"], "secret": "..."}'

Good for: a long-running service that processes many batches over time — dashboards, SaaS backends, anything with a standing HTTP endpoint. Deliveries are HMAC-signed (see building a receiver), retried up to four times over 15 minutes on failure, and the webhook disables itself after ten consecutive failures so a dead endpoint doesn't retry forever.

Webhooks require Pro+ and count against a per-plan limit (5 on Pro, 10 on Business, 25 on Unlimited) — see plans. Each registration takes a URL, a list of events, and a secret you choose — only subscribe to the events you'll actually act on; a handler for an event type you ignore is still a round trip and a signature check for nothing.

Per-batch callback_url

Don't want a standing webhook for a one-off batch? Pass callback_url directly on the submit instead:

curl -s -X POST https://scriptube.me/api/v1/transcripts \
  -H "X-API-Key: YOUR_API_KEY" -H "Content-Type: application/json" \
  -d '{"urls": ["..."], "callback_url": "https://yourapp.example.com/batch-done"}'

It fires batch.completed and transcript.ready for that batch only, signed with your account's webhook secret if you have one registered, or with a one-time callback_secret returned in the submit response (shown once — store it if you'll need to re-verify later). This needs no registration step but has no delivery log — if you need to audit past deliveries, register a real webhook instead.

Picking one

They're not mutually exclusive: it's reasonable to register a webhook as the primary path and fall back to a slow poll (e.g. once an hour) as a safety net in case a delivery is ever missed.

What a webhook costs you in complexity

Polling needs nothing but an HTTP client and a loop. A webhook needs a publicly reachable endpoint, TLS, signature verification (get this wrong and you're trusting unauthenticated POST requests), and a plan for what happens when your endpoint is briefly down — which is exactly what the four-attempt retry ladder is for, but only within a 15-minute window. If your service has real downtime risk, either combine a webhook with a periodic reconciliation poll, or just poll in the first place; for a low-volume integration, the operational cost of running a receiver can outweigh the request savings.

Frequently asked

Can I get a webhook for a single item instead of the whole batch? Yes — subscribe to transcript.ready instead of (or alongside) batch.completed; it fires per video as each one finishes, which is useful for showing live progress on a large batch rather than waiting for the last item.

What if I miss a webhook delivery entirely (endpoint was down past the retry window)? The batch state itself never disappears — a GET /api/v1/transcripts/{batch_id} poll will show you exactly where it ended up, any time after the fact. That's the real argument for a reconciliation poll even on a webhook-first integration.

Does polling cost credits? No — reads never bill. Only the original submit (and a retry of failed items) charges credits; polling or exporting the same batch any number of times is free.

Which should I reach for first on a brand-new integration? Polling, if you're not sure yet. It's simpler to get working and to debug, and switching to a webhook once you understand your own traffic pattern is a small, isolated change — the batch API itself doesn't change underneath you either way.

Next steps

• Build a webhook receiver in Node/TypeScript with signature verification.
• Paginate when polling a batch with hundreds of items.
• Tag batches with external_id/metadata so webhook payloads tell you which of your own jobs just finished.

Full reference: API documentation.