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.

Fehlerbehandlung in webhooks

Wenn eine Generierung fehlschlägt, enthält die webhook-Nutzlast Fehlerinformationen in zwei Feldern: - error: Eine für Menschen lesbare Fehlermeldung, die beschreibt, was schief gelaufen ist - error_code: Ein spezifischer Fehlercode, der für die programmgesteuerte Fehlerbehandlung verwendet werden kann (siehe Anleitung zur Fehlerbehandlung für eine vollständige Liste der Fehlercodes) Diese verbesserte Fehlerstruktur ermöglicht es Ihnen, den Benutzern sowohl aussagekräftige Meldungen anzuzeigen als auch eine spezifische Fehlerbehandlungslogik basierend auf den Fehlercodes zu implementieren.

Ü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 gesamten whsec_...-Wert sicher auf; masked=true dient nur zur Anzeige und darf nicht zur Überprüfung verwendet werden. Die Signatur besteht aus 2 Komponenten: - Zeitstempel (zum Zeitpunkt des Sendens des Ereignisses) - Signatur-Hash (der Zeitstempel und der genaue rohe JSON-Anfragetext)

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