Soll ich Webhooks oder Polling für eine Transkriptions-API nutzen?

Question

Accepted Answer

Webhooks für die Hauptzustellung, Polling als Backup — die robusteste Production-Konfiguration. Polling allein verschwendet Requests, Webhooks allein riskieren verlorene Events.

Transkriptions-Jobs laufen typischerweise asynchron: Du lädst eine Datei hoch, die API gibt dir ein `transcription.id` zurück, und das Ergebnis kommt irgendwann später. Wie erfährst du, dass es fertig ist?

**Polling**
Dein Code fragt die API periodisch: „Ist Job X fertig?" Typisch: alle 2-5 Sekunden ein GET `/v1/transcriptions/{id}/status`. Wenn der Status auf `completed` springt, holst du das Ergebnis.

Vorteile: simpel, keine Public-URL nötig, funktioniert hinter Firewalls und in Background-Jobs.
Nachteile: viele leere Requests (bei 1h Audio in 2 Min Verarbeitung sind das 60-100 Polls), Rate-Limit-Risiko, max Latenz = Polling-Intervall.

**Webhooks**
Du registrierst eine URL, die API ruft sie an, sobald der Job fertig ist. POST mit Body wie `{ "event": "transcription.completed", "id": "…", "result": { … } }`. Signiert mit HMAC-SHA256, damit du verifizieren kannst, dass es wirklich der Anbieter ist.

Vorteile: keine leeren Requests, Sub-Sekunden-Latenz, skaliert auf Millionen Jobs.
Nachteile: braucht öffentliche URL (oder Tunneling wie ngrok in Dev), du musst Retry, Idempotency und Signatur-Verifikation selbst implementieren. Wenn der Webhook fehlschlägt (Server down, Netzwerk weg), kann das Event verloren gehen.

**Die richtige Antwort: beides**
Produktive Systeme kombinieren beide. Webhooks als primäre Zustellung — schnell, effizient. Polling als Backstop alle 5-10 Minuten für Jobs, die seit > 30 Min auf `completed` warten — fängt Fälle ab, in denen der Webhook verloren ging.

**Konkretes Pattern**
```
// Bei 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 })
})

// Backup-Job (cron, alle 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-Spezifika**
Wir unterstützen beide Wege: Webhooks via `POST /v1/webhooks` registrieren (Events: `transcription.completed`, `transcription.failed`, `balance.low`), Polling via `GET /v1/transcriptions/{id}/status`. Für Echtzeit-UI im Browser bieten wir zusätzlich SSE (`GET /v1/transcriptions/{id}/events`) — Server-Sent Events streamen Status-Updates direkt in den Client, ohne dass du einen WebSocket-Channel öffnen musst.

Soll ich Webhooks oder Polling für eine Transkriptions-API nutzen?

Verwandte Fragen

Frage offen geblieben?