Moet ik webhooks of polling gebruiken voor een transcriptie-API?

Transcriptiejobs zijn doorgaans async: je uploadt een bestand, de API geeft een `transcription.id` terug, en het resultaat komt later. Hoe kom je erachter dat het klaar is?

Polling Je code vraagt de API periodiek: „Is job X klaar?\" Typisch: GET `/v1/transcriptions/{id}/status` om de 2-5 seconden. Als de status omslaat naar `completed`, haal je het resultaat op.

Voordelen: eenvoudig, geen publieke URL nodig, werkt achter firewalls en in achtergrondjobs. Nadelen: veel lege requests (een bestand van 1 uur dat in 2 min wordt verwerkt kost 60-100 polls), risico op rate limits, max latentie = polling-interval.

Webhooks Je registreert een URL; de API roept die aan wanneer de job klaar is. POST met een body als `{ "event": "transcription.completed", "id": "…", "result": { … } }`. Ondertekend met HMAC-SHA256, zodat je kunt verifiëren dat het echt de aanbieder is.

Voordelen: geen lege requests, latentie onder een seconde, schaalt naar miljoenen jobs. Nadelen: vereist een publieke URL (of een tunnel als ngrok in dev), je moet zelf retry, idempotentie en handtekeningverificatie implementeren. Als de webhook-levering mislukt (server down, netwerkstoring), kan het event verloren gaan.

Het juiste antwoord: allebei Productiesystemen combineren de twee. Webhooks voor de primaire levering – snel, efficiënt. Polling als vangnet om de 5-10 minuten voor jobs die al > 30 min in de wachtrij staan – vangt gevallen op waarin de webhook verloren ging.

Concreet patroon ``` // Bij upload const job = await api.transcribe({ file, webhook_url: "https://…" }) await db.insert({ id: job.id, status: "queued" })

// Webhook-endpoint app.post("/webhook", (req) => { if (!verifySignature(req)) return 401 await db.update(req.body.id, { status: "completed", result: req.body.result }) })

// Back-upjob (cron, om de 10 min) const stuck = await db.where("status", "queued").and("createdAt", "<", now-30min) for (const j of stuck) { const fresh = await api.getStatus(j.id) if (fresh.status === "completed") await db.update(j.id, fresh) } ```

DeepScript-specifiek We ondersteunen beide: registreer webhooks via `POST /v1/webhooks` (events: `transcription.completed`, `transcription.failed`, `balance.low`), poll via `GET /v1/transcriptions/{id}/status`. Voor real-time UI in de browser bieden we ook SSE (`GET /v1/transcriptions/{id}/events`) – server-sent events streamen statusupdates rechtstreeks naar de client zonder dat je een WebSocket-kanaal opent.