Webhook-Zustellung

Sie haben eine Jobgruppe erstellt und innerhalb von Millisekunden ein 202 erhalten. Die Übersetzungen laufen jetzt im Hintergrund, ein Job pro Sprache. Sie könnten jeden Job pollen, bis er abgeschlossen ist – aber Sie möchten keine Polling-Schleife laufen lassen, nur um zu erfahren, dass Deutsch fertig ist. Sie möchten, dass Ihr Server genau dann benachrichtigt wird, wenn jede Sprache eintrifft.

Genau dafür ist der Webhook da. Wenn Sie beim Erstellen von Jobs eine callbackUrl übergeben, sendet Lingo das Ergebnis per POST an diese URL, sobald ein Job einen Endzustand erreicht – ein POST pro Sprache, genau in dem Moment, in dem sie fertig ist. Eine Sprache, die erfolgreich übersetzt wurde, kommt als translation.completed mit den Daten an. Eine Sprache, die fehlschlägt, kommt als translation.failed mit dem Fehler an. Sie werden in jedem Fall informiert – pro Sprache, ohne nachfragen zu müssen.

Auf dieser Seite geht es um die beiden Payloads und darum, wie Sie damit umgehen. Die Zustellung ist signiert und wird bei Bedarf erneut versucht – dieser Mechanismus wird mit dem Provisioning geteilt und ist auf der Seite Webhook-Signaturprüfung dokumentiert, auf die wir an jeder relevanten Stelle verlinken.

Auf dieser Seite

• So funktioniert die Zustellung
• Die Payload bei erfolgreichem Abschluss
• Die Payload bei Fehlschlag
• Umgang mit einem Webhook
• Wann Zustellung das falsche Werkzeug ist

So funktioniert die Zustellung#

Jede Sprache in einer Gruppe ist ein eigenständiger Job. Sobald eine davon einen Endzustand erreicht, wird ihr Ergebnis einzeln an Ihre callbackUrl zugestellt – Lingo wartet nicht auf die langsamste Sprache und bündelt die Gruppe nicht zu einem einzigen Aufruf. Vierzehn Zielsprachen bedeuten bis zu vierzehn POSTs, die jeweils dann eintreffen, wenn die einzelne Sprache fertig ist – in genau der Reihenfolge, in der sie fertig werden.

Legen Sie das Ziel pro Anfrage mit callbackUrl fest, wenn Sie die Jobgruppe erstellen, oder definieren Sie im Dashboard einen Standardwert für die Organisation, den jede Gruppe übernimmt. Eine callbackUrl pro Anfrage überschreibt den Organisationsstandard für diese Gruppe.

Übertragen werden zwei Payload-Formen, unterschieden über ihr Feld type: translation.completed und translation.failed. Beide nennen den Job und die Gruppe, zu denen sie gehören, sowie die Sprache, die sie transportieren. So kann ein einzelner Handler anhand von type routen und den richtigen Datensatz aktualisieren.

Die Payload bei erfolgreichem Abschluss#

Wenn ein Job erfolgreich abgeschlossen wird, enthält die Payload die übersetzten data – in derselben Form, die Sie auch beim Abrufen des Jobs erhalten würden, nur dass sie Ihnen zugestellt statt abgefragt werden. Die data spiegelt die Struktur wider, die Sie eingereicht haben: jede Zeichenkette übersetzt, jeder Nicht-String-Wert (Zahlen, boolesche Werte, null) unverändert, die Verschachtelung bleibt erhalten.

{
  "type": "translation.completed",
  "jobId": "ljb_A1b2C3d4E5f6G7h8",
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "sourceLocale": "en",
  "targetLocale": "de",
  "data": {
    "id": "course_101",
    "title": "Einführung in maschinelles Lernen",
    "steps": [
      { "heading": "Was ist ML?", "body": "Maschinelles Lernen ist ein Teilbereich der künstlichen Intelligenz." },
      { "heading": "Überwachtes Lernen", "body": "Trainieren eines Modells mit gelabelten Daten." }
    ],
    "metadata": { "author": "Dr. Smith", "difficulty": "beginner" }
  }
}

Ein Job, der Output erzeugt, ist kein Fehlschlag – deshalb wird ein Job, der als completed_with_warnings abgeschlossen wurde (Output wurde erzeugt, aber eine optionale pipeline-Stufe ist durchgefallen), als translation.completed mit verwendbaren data zugestellt. Der Webhook teilt Ihnen mit, dass die Sprache bereit ist; die Warnungen pro Schritt, die das Durchfallen erklären, finden Sie im einzelnen Job, den Sie per jobId abrufen können, wenn Sie sie benötigen.

Die Payload bei Fehlschlag#

Eine Sprache kann fehlschlagen – ein Modell kann ein Timeout haben, oder alle konfigurierten Modelle sind nicht verfügbar. Wenn ein Job failed erreicht, werden Sie trotzdem informiert. Der Payload-Typ ist translation.failed und enthält eine error-Zeichenkette anstelle von data:

{
  "type": "translation.failed",
  "jobId": "ljb_C3d4E5f6G7h8I9j0",
  "groupId": "ljg_A1b2C3d4E5f6G7h8",
  "sourceLocale": "en",
  "targetLocale": "ja",
  "error": "Model timeout after 30 seconds"
}

Der Fehlschlag betrifft immer nur eine einzelne Sprache. Wenn Sie de, fr und ja eingereicht haben, wird ein Fehlschlag von ja als eigener translation.failed-POST zugestellt, während de und fr als translation.completed eintreffen – die deutschen und französischen Übersetzungen werden also trotzdem ausgeliefert. Der Status bei partiellem Fehlschlag der Gruppe spiegelt diese Mischung wider. Um die fehlgeschlagene Sprache erneut zu verarbeiten, senden Sie einen neuen Job nur für diese Sprache mit einem frischen Idempotency-Key.

Umgang mit einem Webhook#

Der erste Gedanke skeptischer Leser ist hier genau richtig: Mein Handler erledigt echte Arbeit – einen Datenbankschreibvorgang, eine Cache-Invalidierung, ein Fan-out an verbundene Clients – hält das die Verbindung nicht so lange offen, dass der Webhook in ein Timeout läuft?

Doch – also lassen Sie Lingo nicht darauf warten. Geben Sie zuerst 200 zurück und verarbeiten Sie danach. Bestätigen Sie den Empfang sofort und erledigen Sie die eigentliche Arbeit erst, nachdem die Antwort gesendet wurde. Ein Handler, der schnell zurückkehrt, hält die Zustellung zuverlässig; ein Handler, der auf nachgelagerte Arbeit wartet, provoziert unnötige Wiederholungsversuche.

app.post("/webhooks/translations", verifyWebhook, async (req, res) => {
  // Acknowledge first - one POST per locale, the moment it lands.
  res.status(200).send("ok");

  const { type, jobId, groupId, targetLocale, data } = req.body;

  if (type === "translation.completed") {
    await db.content.update({
      where: { groupId },
      data: { [`content_${targetLocale}`]: data },
    });

    // Advance your own progress model - your UI can poll this or receive it over SSE.
    await db.translationProgress.increment({
      where: { groupId },
      data: { completedLanguages: { increment: 1 } },
    });
  }

  if (type === "translation.failed") {
    console.error(`Translation failed: ${jobId} (${targetLocale})`, req.body.error);
  }
});

Die Middleware verifyWebhook ist der eine Baustein, den diese Seite nicht selbst definiert. Jede Zustellung ist nach der Spezifikation Standard Webhooks signiert – Sie müssen also kein proprietäres Schema per Reverse Engineering entschlüsseln. Wie Sie die Signatur verifizieren – und welcher Wiederholungsplan hinter einer Nicht-2xx-Antwort steckt – ist vollständig auf Webhook-Signaturprüfung dokumentiert, gemeinsam mit dem Provisioning. Binden Sie diese Middleware ein, bevor Sie einer Payload vertrauen: Ein nicht verifizierter Body ist ein nicht authentifizierter Body.

Wann Zustellung das falsche Werkzeug ist#

Der Webhook ist eine praktische Push-Lösung, nicht das führende System. In zwei Fällen brauchen Sie etwas anderes – und beides ist nur einen Link entfernt.

Wenn Ihr Endpunkt nicht erreichbar war, als ein Ergebnis zugestellt wurde, versucht die Plattform es erneut – und selbst wenn alle Wiederholungsversuche ausgeschöpft sind, geht das Ergebnis nicht verloren. Es bleibt über jobId abrufbar; der callbackStatus des Jobs hält fest, ob die Zustellung am Ende erfolgreich war. Der Wiederholungsplan selbst ist auf der Seite zu Signatur und Zustellung dokumentiert. Der Webhook erspart Ihnen im Regelfall eine Polling-Schleife; der Jobdatensatz ist im Ausnahmefall trotzdem immer die verlässliche Grundlage darunter.

Und wenn Sie Live-Fortschritt in einer UI möchten – einen Zähler, der beim Eintreffen der Sprachen von 3 von 14 auf 4 von 14 springt, statt eines Callbacks pro Sprache an Ihren Server –, dann ist das der Jobgruppen-WebSocket, nicht der Webhook.