Webhooks vs. Polling für Transkripte: Die asynchrone Entscheidung

Nutzen Sie Polling, wenn Sie weniger als 50 Jobs pro Tag haben oder ein Nutzer aktiv wartet. Steigen Sie auf Webhooks um, wenn Sie über etwa 100 Jobs pro Tag hinausgehen und die Jobs im Hintergrund laufen. Das ist die Entscheidung in zwei Sätzen. Alles Weitere sind die Implementierungsdetails, die den Unterschied ausmachen zwischen einem Webhook, der funktioniert, und einem, der um 2 Uhr nachts stillschweigend Transkripte verliert.

Die Ressourcen-Rechnung

Ein konkretes Beispiel. Sie transkribieren 200 Jobs pro Tag. Jeder dauert im Durchschnitt 3 Minuten.

Polling alle 5 Sekunden:

• Pro Job: durchschnittlich 36 Poll-Anfragen (3 Min. x 12 Abfragen/Min.)
• Täglich: 7.200 Poll-Anfragen
• Nützliche Ergebnisse in diesen Anfragen: etwa 1 %

Webhooks:

• Pro Job: 1 Übermittlung + 1 Webhook-Zustellung
• Täglich: 200 Übermittlungen + 200 Webhooks = 400 Ereignisse
• 100 % der Ereignisse enthalten ein Ergebnis

Bei diesem Volumen sind Webhooks 18-mal effizienter. Bei 2.000 Jobs pro Tag wird Polling auf beiden Seiten der API wirklich teuer, und die meisten Anbieter drosseln Ihre Statusabfragen, bevor sie Ihre Übermittlungen drosseln.

Wann Polling weiterhin die richtige Wahl ist

Sie haben keinen öffentlichen HTTP-Endpunkt. Lokale Entwicklungsumgebungen, Mobile-first-Apps ohne Backend und interne Tools hinter einem VPN können keine Webhook-Zustellungen empfangen. Polling benötigt lediglich ausgehendes HTTP.

Das Volumen liegt unter 50 Jobs pro Tag. Der Ressourcenaufwand ist vernachlässigbar. Die Einfachheit einer Polling-Schleife überwiegt den Infrastrukturaufwand eines Webhook-Empfängers.

Der Nutzer schaut aktiv zu. Ein Nutzer hat ein Interview hochgeladen und starrt auf einen Fortschrittsbalken. Polling liefert Ihnen etwas, womit Sie die UI aktualisieren können. Webhooks würden zusätzliche Verdrahtung erfordern (WebSocket, Server-Sent Events oder ein Push-Dienst), um das Abschluss-Signal zurück an den Browser weiterzuleiten. Eine funktionierende Polling-Schleife finden Sie unter Entwicklung mit Transkriptions-APIs.

Wann der Wechsel zu Webhooks sinnvoll ist

Drei Signale:

Das Volumen überschreitet die Marke von 100 Jobs pro Tag. Die Infrastrukturkosten eines Webhook-Empfängers amortisieren sich durch eingesparte API-Aufrufe innerhalb einer Woche.

Latenz spielt keine Rolle, weil der Nutzer nicht zuschaut. Hintergrundverarbeitung von Aufnahmen, die in einer Datenbank landen, um sie später abzufragen. Der Nutzer sieht das Ergebnis, sobald er das Dashboard das nächste Mal öffnet.

Ergebnisse müssen verteilt werden. Ein Webhook kann Ihren Datenbank-Schreibvorgang, eine Slack-Benachrichtigung und ein HubSpot-Update gleichzeitig auslösen. Polling muss dies in Ihrem Anwendungscode nacheinander erledigen. Rezepte für das Fan-out finden Sie unter Transkription mit Slack integrieren, Notion oder HubSpot.

Welche Transkriptions-APIs tatsächlich Webhooks unterstützen

Das variiert stärker, als die Dokumentation vermuten lässt.

AWS Transcribe bietet überhaupt keine Webhook-Zustellung. Sie übermitteln einen Job und fragen dann GetTranscriptionJob ab, bis TranscriptionJobStatus gleich COMPLETED ist. Das LongRunningRecognize von Google Cloud Speech-to-Text gibt ein Operation-Handle zurück, das Sie mit Operations.get abfragen, bis done wahr ist. Der Endpunkt /v1/audio/transcriptions von OpenAI ist vollständig synchron: Sie blockieren, bis die Antwort zurückkommt oder ein Timeout auftritt.

Meine Einschätzung: Von den drei Anbietern, die asynchrone Zustellung unterstützen, ist Deepgrams Callback-Mechanismus am besten für den Produktivbetrieb geeignet. AssemblyAIs Payload liefert bei Abschluss nur eine transcript_id und ein status-Feld, d. h. Sie benötigen immer einen zweiten API-Aufruf, um das tatsächliche Transkript abzurufen. Deepgram sendet das vollständige Ergebnis an Ihre Callback-URL.

Einen genaueren Blick darauf, wie die großen APIs ihre Nutzung bepreisen, finden Sie unter Speech-to-Text-API-Preise 2026.

Einen Webhook einrichten (ConvertAudioToText API)

Der Registrierungsaufruf:

curl -X POST https://api.convertaudiototext.com/api/v1/dashboard/webhooks \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/transcription",
    "events": ["job.completed", "job.failed"]
  }'

Die Antwort enthält ein secret-Feld. Speichern Sie es. Die API generiert das Secret serverseitig und gibt es einmalig bei der Erstellung zurück. Es wird nicht in wiederherstellbarer Form gespeichert.

Verfügbare Ereignisse: job.queued, job.processing, job.completed, job.failed. Die meisten Integrationen abonnieren nur job.completed und job.failed.

HMAC-Signaturvalidierung

Jede Zustellung enthält einen X-Webhook-Signature-Header mit dem Wertformat sha256=<hex>. Die Signatur lautet HMAC-SHA256(secret, raw_body).

In Node:

import crypto from 'crypto';
import express from 'express';

const app = express();

app.post('/webhooks/transcription',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const sig = req.header('X-Webhook-Signature');
    const expected = 'sha256=' + crypto
      .createHmac('sha256', process.env.WEBHOOK_SECRET)
      .update(req.body)
      .digest('hex');

    if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
      return res.status(401).send('Invalid signature');
    }

    const event = JSON.parse(req.body.toString());
    handleTranscript(event);
    res.sendStatus(200);
  }
);

In Python:

import hmac
import hashlib

def verify(signature: str, body: bytes, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(signature, expected)

Verwenden Sie timingSafeEqual (Node) oder hmac.compare_digest (Python). Naiver String-Vergleich gibt über das Antwort-Timing Informationen preis.

Den Body erst nach der Validierung parsen, niemals davor. Middleware, die JSON parst, bevor Ihr Handler läuft, verbraucht die rohen Bytes und macht die Signaturberechnung unmöglich. Das express.raw()-Beispiel oben ist bewusst so gewählt: Sie erhalten zuerst den Rohpuffer und parsen erst danach.

Idempotenz

Der Zustellungs-Worker kann für dasselbe Ereignis mehrfach auslösen. Netzwerke versagen. Ihr Handler kann ein Ereignis verarbeiten und abstürzen, bevor er 200 zurückgibt. Der Anbieter wiederholt den Versuch. Ihr Handler läuft erneut.

Jedes Ereignis hat eine eindeutige event_id (in der Payload verfügbar). Das sichere Muster:

async function handleTranscript(event) {
  const inserted = await db.query(
    `INSERT INTO processed_events (event_id) VALUES ($1)
     ON CONFLICT DO NOTHING RETURNING id`,
    [event.data.job_id + ':' + event.event]
  );

  if (inserted.rowCount === 0) return;

  await saveTranscript(event.data.job_id, event.data.result_url);
}

ON CONFLICT DO NOTHING bedeutet, dass doppelte Zustellungen stillschweigend enden. Die erste Zustellung gewinnt; Duplikate werden ignoriert, ohne Fehler auszulösen.

Retry-Verhalten

Der ConvertAudioToText-Zustellungs-Worker wiederholt fehlgeschlagene Zustellungen nach diesem Zeitplan (insgesamt 5 Versuche):

Nach 5 fehlgeschlagenen Versuchen wird die Zustellung als failed markiert. Den Zustellungsverlauf können Sie im Webhook-Dashboard einsehen und dort manuelle Wiederholungen auslösen, oder Sie nutzen den Retry-Endpunkt:

curl -X POST https://api.convertaudiototext.com/api/v1/dashboard/webhooks/deliveries/{delivery_id}/retry \
  -H "Authorization: Bearer $API_KEY"

Damit sich Ihr Handler korrekt verhält: Geben Sie 2xx für Erfolg zurück, 4xx für dauerhafte Fehler (keine Wiederholung nötig), 5xx für vorübergehende Fehler (Wiederholung erwünscht). Antworten Sie innerhalb von 30 Sekunden. Ist Ihre Verarbeitung langsam, bestätigen Sie sofort und stellen die eigentliche Arbeit in die Warteschlange:

app.post('/webhooks/transcription', (req, res) => {
  validateSignature(req);
  jobQueue.push(req.body);
  res.sendStatus(200); // ack first, process after
});

Lokale Entwicklung

Webhooks benötigen eine öffentliche HTTPS-URL. Zwei Ansätze, die funktionieren:

ngrok- oder cloudflared-Tunnel. Stellt Ihren lokalen Server über eine temporäre URL ins Internet bereit.

ngrok http 3000
# Use the resulting https URL as your webhook URL

Dual-Mode-Handler. Webhooks in der Produktion, Polling in der lokalen Entwicklung. Eine Umgebungsvariable schaltet das Verhalten um. So bleibt die lokale Feedback-Schleife einfach, ohne den Produktionscode zu ändern.

Produktionsmuster

Direkt in die Datenbank. Der Handler schreibt das Transkript in Postgres oder MongoDB und gibt 200 zurück. Nachgelagerter Code fragt die Datenbank ab. Das einfachste Muster, funktioniert in jeder Größenordnung.

Direkte Integration. Der Handler postet in Slack, erstellt eine Notion-Seite oder aktualisiert einen HubSpot-Kontakt. Gut, wenn die Integration das Hauptziel ist. Schlägt laut fehl (5xx), wenn das nachgelagerte System ausgefallen ist, was automatisch Wiederholungen auslöst.

Event-Bus. Der Handler veröffentlicht in Kafka, SNS oder ein internes Pub/Sub-Topic. Mehrere Consumer verarbeiten dasselbe Ereignis unabhängig voneinander. Entkoppelt den Webhook-Empfang von der nachgelagerten Verarbeitung. Das richtige Muster für große Pipelines, in denen mehrere Systeme dasselbe Transkript konsumieren. Zur Pipeline-Architektur siehe Batch-Transkription für große Projekte.

Beide Muster kombinieren

Manchmal wollen Sie beides. Der Nutzer lädt eine Datei hoch. Ihr Backend übermittelt den Job und beginnt mit dem Polling für UI-Updates. Der Webhook feuert bei Abschluss und wird zum maßgeblichen Datensatz in Ihrer Datenbank. Der Nutzer erhält sofortiges Feedback; das Backend erhält ein zuverlässiges asynchrones Signal, das nicht davon abhängt, dass die UI geöffnet bleibt.

Dieser duale Ansatz erfordert mehr Code, liefert aber die beste Nutzererfahrung, wenn Nutzer aktiv auf Ergebnisse von Dateien warten, die ihnen wichtig sind, während das System zugleich Hintergrund-Jobs zuverlässig abwickelt.

Wenn Sie einfach nur saubere Transkripte brauchen, ohne eine Backend-Integration zu bauen, erledigt ConvertAudioToText die gesamte Pipeline im Browser – ganz ohne API-Schlüssel.

FAQ

Wann sollte ich beim Transkribieren Polling statt Webhooks verwenden?

Nutzen Sie Polling, wenn Sie keinen öffentlichen HTTP-Endpunkt haben (lokale Entwicklung, Tools nur hinter einem VPN, mobile Apps ohne Backend), wenn das Volumen unter 50 Jobs pro Tag liegt oder wenn ein Nutzer aktiv wartet und Sie einen Fortschrittsbalken in Echtzeit aktualisieren müssen. Webhooks verursachen Infrastrukturkosten, die sich bei geringem Volumen nicht rechtfertigen.

Welche großen Transkriptions-APIs unterstützen Webhooks?

AssemblyAI unterstützt Webhooks über einen webhook_url-Parameter (10 Wiederholungsversuche, 10 Sekunden Timeout). Deepgram unterstützt einen callback-Query-Parameter mit dg-token-Header-Verifizierung und 10 Wiederholungen alle 30 Sekunden. Rev.ai verwendet ein notification_config-Objekt mit bis zu 24 Stunden Wiederholungsversuchen. AWS Transcribe und Google Cloud Speech-to-Text erfordern Polling: AWS über GetTranscriptionJob und Google über die Operations.get-Schnittstelle für langlaufende Operationen. OpenAI Whisper ist vollständig synchron und bietet keinerlei asynchrone Zustellung.

Wie validiere ich, dass ein Webhook von der richtigen Quelle stammt?

Das Standardmuster ist HMAC-SHA256: Der Anbieter signiert den rohen Request-Body mit Ihrem gemeinsamen Geheimnis und legt das Ergebnis in einem Header ab. Ihr Handler berechnet denselben HMAC neu und vergleicht ihn mit einer timing-sicheren Gleichheitsfunktion. Verwenden Sie niemals einen einfachen String-Vergleich, der über das Timing Informationen preisgibt. Deepgram nutzt einen anderen Mechanismus (einen dg-token-Header, der an Ihren API-Schlüssel gebunden ist), daher variiert der Ansatz je nach Anbieter.

Was soll mein Webhook-Handler zurückgeben und wie schnell?

Geben Sie einen 2xx-Statuscode zurück, um den Empfang zu bestätigen – und zwar innerhalb des Timeout-Fensters Ihres Anbieters (30 Sekunden sind üblich). Wenn Ihre eigentliche Verarbeitung aufwendig ist, bestätigen Sie sofort und stellen die Arbeit in eine Warteschlange. Geben Sie 5xx für vorübergehende Fehler zurück, die wiederholt werden sollen, und 4xx für dauerhafte Fehler, die nicht wiederholt werden sollen. Langsame Antworten lösen Retry-Stürme aus, die Ihre Zustellungswarteschlange blockieren können.

Quellen

• AssemblyAI-Webhook-Dokumentation: https://www.assemblyai.com/docs/getting-started/webhooks (geprüft am 2026-07-02)
• Deepgram-Callback-Dokumentation: https://developers.deepgram.com/docs/callback (geprüft am 2026-07-02)
• Rev.ai-Webhook-Dokumentation: https://docs.rev.ai/api/asynchronous/webhooks/ (geprüft am 2026-07-02)
• AWS Transcribe GetTranscriptionJob: https://docs.aws.amazon.com/transcribe/latest/APIReference/API_GetTranscriptionJob.html (geprüft am 2026-07-02)
• Google Cloud STT LongRunningRecognize: https://cloud.google.com/speech-to-text/docs/reference/rest/v1/speech/longrunningrecognize (geprüft am 2026-07-02)
• OpenAI Speech-to-Text-API: https://developers.openai.com/api/docs/guides/speech-to-text (geprüft am 2026-07-02)