webhooks

Sync Labs webhooks liefern HTTP POST-Benachrichtigungen in Echtzeit, wenn Ihre lip sync-Generierungsjobs abgeschlossen sind oder fehlschlagen. Verwenden Sie webhooks anstelle von Abfragen, um effiziente, ereignisgesteuerte Workflows zu erstellen, die ohne wiederholte API-Aufrufe auf Änderungen des Generierungsstatus reagieren.

Wie richte ich webhooks ein?

So verwenden Sie webhooks:

1. Geben Sie einen webhookUrl-Parameter an, wenn Sie einen API endpoint aufrufen, der ihn unterstützt.
2. Stellen Sie sicher, dass Ihr webhook endpoint HTTP POST-Anfragen empfangen und verarbeiten kann und die [Webhook-Nutzlast für Statusaktualisierungen] (/api-reference/api/webhooks-payload-reference/webhooks) nutzen kann.

Durch die Nutzung von webhooks können Sie Ihren Arbeitsablauf mit nicht blockierenden Anrufen optimieren, sodass Sie sich auf andere Aufgaben konzentrieren können, während Sie Benachrichtigungen über den Abschluss von Aufträgen erhalten. Wenn Sie keine Ereignisse empfangen, bestätigen Sie, dass der genaue webhookUrl in der Generierungsanforderung enthalten war, dass der endpoint über HTTPS öffentlich erreichbar ist und dass er schnell eine 2xx-Antwort auf POST-Anfragen zurückgibt. Wenn die Zustellung verpasst wird, weil Ihr endpoint nicht verfügbar ist oder die Anfrage ablehnt, fragen Sie als Ausweichlösung den Generierungsstatus endpoint ab.

Wann werden webhooks gesendet?

Ein Generierungs-webhook wird gesendet, sobald die Generierung einen Endstatus erreicht: COMPLETED, FAILED oder REJECTED. Ein Batch-webhook wird gesendet, wenn der Batch COMPLETED oder FAILED ist.

Jede Anfrage enthält diese Header:

Wiederholungen und Duplikate

Sync wiederholt webhooks, die Ihr endpoint nicht angenommen hat, für Generierungen und Batches gleichermaßen:

• Bis zu 6 Versuche über etwa 2 Stunden. Die Wiederholungen warten etwa 1, 3, 9, 27 und 60 Minuten (±25 % Streuung).
• Was wiederholt wird: Timeouts, Verbindungsfehler sowie 429- und 5xx-Antworten. Ein Retry-After-Header in diesen Antworten ersetzt die berechnete Wartezeit (zwischen 1 Sekunde und 60 Minuten).
• Was nicht wiederholt wird: jede andere 4xx-Antwort, einschließlich 408, eine ungültige URL oder eine andere Weiterleitung als 307/308. Die Zustellung endet bei der ersten solchen Antwort.
• Timeout: Jeder Versuch wartet bis zu 10 Sekunden auf Ihre Antwort. Antworten Sie sofort mit 2xx und erledigen Sie langsame Arbeit danach.
• Ziele: Die URL muss auf eine öffentliche Adresse auflösen. Bis zu drei 307/308-Weiterleitungen werden verfolgt.

Eine Wiederholung kann eintreffen, nachdem Ihr endpoint das Ereignis bereits verarbeitet hat, zum Beispiel wenn Ihre 2xx-Antwort das Timeout überschritten hat. Behandeln Sie deshalb Duplikate: Deduplizieren Sie anhand des Headers Sync-Delivery-Id oder der id der Generierung bzw. des Batches im Payload. Jeder Versuch wird mit einem neuen Zeitstempel neu signiert, daher unterscheidet sich der Wert von Sync-Signature zwischen Versuchen derselben Zustellung.

Schlagen alle Versuche fehl, wird das Ereignis nicht erneut gesendet. Rufen Sie Get Generation oder Get Batch ab, um verpasste Ergebnisse zu erhalten.

Fehlerbehandlung in webhooks

Der Payload des Generierungs-webhooks hat für id, createdAt, status, model, input, webhookUrl, options und outputUrl dieselben Felder wie Get Generation, dazu synthesizedAudioUrl bei Generierungen mit Texteingabe. Wenn eine Generierung fehlschlägt oder abgelehnt wird, beschreiben zwei Felder den Grund; sonst sind beide null:

• error: Eine für Menschen lesbare Fehlermeldung, die beschreibt, was schief gelaufen ist
• errorCode: Ein maschinenlesbarer Fehlercode für die programmgesteuerte Fehlerbehandlung (siehe Anleitung zur Fehlerbehandlung und GET /v2/errors für die vollständige Liste)

{
  "id": "0f8b1c2d-3e4f-4a5b-8c6d-7e8f9a0b1c2d",
  "createdAt": "2026-01-10T12:00:00.000Z",
  "status": "FAILED",
  "model": "lipsync-2",
  "input": [
    { "type": "video", "url": "https://example.com/video.mp4" },
    { "type": "audio", "url": "https://example.com/audio.mp3" }
  ],
  "webhookUrl": "https://example.com/webhook",
  "options": {},
  "outputUrl": null,
  "error": "The provided video URL is inaccessible.",
  "errorCode": "generation_input_video_inaccessible"
}

Verzweigen Sie anhand von errorCode, nicht anhand des Meldungstexts. Alle Felder finden Sie in der Payload-Referenz.

Überprüfen Sie die webhook-Signaturen

Um sicherzustellen, dass webhook-Anfragen von Sync Labs kommen, signieren wir jede webhook-Anfrage mit einer Signatur. Die Signatur ist im Sync-Signature-Header enthalten.

Um Signaturen zu überprüfen, verwenden Sie Ihr Signaturgeheimnis. Sie können es auch programmgesteuert mit GET /v2/organizations/webhook/secret abrufen. Bewahren Sie den vollständigen Wert whsec_... sicher auf; masked=true dient nur der Anzeige und darf nicht zur Überprüfung verwendet werden.

Der Header hat die Form t=<Zeitstempel>,v1=<Signatur>:

• t: die Unix-Zeit in Sekunden, zu der dieser Versuch gesendet wurde
• v1: der HMAC-SHA256 als Hex von <t>.<roher Anfrage-Body>, mit Ihrem Signaturgeheimnis als Schlüssel

Berechnen Sie den HMAC über die exakt empfangenen Bytes, nicht über neu serialisiertes JSON. Um Wiederholungsangriffe zu begrenzen, können Sie zusätzlich Anfragen ablehnen, deren t weit von Ihrer aktuellen Zeit abweicht; lassen Sie einige Minuten Spielraum für Uhrabweichungen.

const express = require("express");
const { createHmac, timingSafeEqual } = require("crypto");
const app = express();
const WEBHOOK_SECRET = "whsec_";
// Keep the exact request bytes for signature verification.
app.use("/webhook", express.raw({ type: "application/json" }));
const verifySignature = (rawBody, signature, secret) => {
  try {
    if (!signature) {
      return false;
    }
    const [, timestamp, receivedSignature] =
      signature.match(/t=(\d+),v1=(.+)/) ?? [];
    if (!timestamp || !receivedSignature) {
      return false;
    }
    const signedPayload = Buffer.concat([
      Buffer.from(`${timestamp}.`),
      rawBody,
    ]);
    const expectedSignature = createHmac("sha256", secret)
      .update(signedPayload)
      .digest("hex");
    // Timing-safe comparison to prevent timing attacks
    return timingSafeEqual(
      Buffer.from(receivedSignature),
      Buffer.from(expectedSignature)
    );
  } catch (error) {
    return false;
  }
};
app.post("/webhook", (req, res) => {
  const signature = req.headers["sync-signature"];
  if (!verifySignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(400).json({
      message: "Invalid signature",
    });
  }
  return res.status(200).json({
    message: "Webhook signature verified",
  });
});
app.listen(8080, () => {});

Verwandte Ressourcen - batchverarbeitung - verwenden Sie webhooks mit der batch-Verarbeitung für Arbeitsabläufe mit hohem Volumen - Ratenbegrenzungen - Verstehen Sie das API rate limiting und wie es sich auf die webhook-Lieferung auswirkt

Häufig gestellte Fragen