> For the documentation index, fetch https://sync.so/docs/llms.txt. Append .md to a page URL for Markdown. Documentation-search MCP: https://sync.so/docs/_mcp/server.

# webhooks

> Richten Sie webhooks für Statusaktualisierungen der lip sync-Generierung in Echtzeit ein. Enthält Signaturüberprüfung, Fehlerbehandlung und Codebeispiele.

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.

> **Note**
>
> Aus Sicherheitsgründen muss Ihr webhook URL so konfiguriert sein, dass er und akzeptiert
> Verarbeiten Sie HTTPS `POST`-Anfragen.

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](/developer-guides/error-handling) 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](https://sync.so/settings/webhooks). Sie können es auch programmgesteuert mit [`GET /v2/organizations/webhook/secret`](/api-reference/api/organizations-api/get-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)

**`Javascript`**

```javascript Javascript
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, () => {});
```

**`Python`**

```python Python
import hmac
import hashlib
import re
from flask import Flask, request, jsonify

app = Flask(__name__)

WEBHOOK_SECRET = 'whsec_'


def verify_signature(raw_body: bytes, signature: str, webhook_secret: str) -> bool:
    if not signature:
        return False

    try:
        match = re.match(r't=(\d+),v1=(.+)', signature)
        if not match:
            return False

        timestamp, received_signature = match.groups()
        if not timestamp or not received_signature:
            return False

        expected_signature = hmac.new(
            webhook_secret.encode("utf-8"),
            timestamp.encode("utf-8") + b"." + raw_body,
            hashlib.sha256
        ).hexdigest()

        # Timing-safe comparison to prevent timing attacks
        return hmac.compare_digest(received_signature, expected_signature)
    except Exception:
        return False


@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('Sync-Signature')

    if not verify_signature(request.get_data(cache=True), signature, WEBHOOK_SECRET):
        return jsonify({'message': 'Invalid signature'}), 400

    return jsonify({'message': 'Webhook signature verified'}), 200


if __name__ == "__main__":
    app.run(host='0.0.0.0', port=8085)

```

## Häufig gestellte Fragen

#### Wie teste ich webhooks lokal?

Verwenden Sie ein Tunneltool wie ngrok, um Ihren lokalen Server dem Internet zugänglich zu machen. Starten Sie Ihren webhook endpoint lokal und führen Sie dann ngrok aus, um einen öffentlichen HTTPS URL zu erhalten. Übergeben Sie diesen URL als webhookUrl, wenn Sie eine Generation erstellen. Sync Labs sendet POST-Anfragen über den Tunnel an Ihren lokalen Server.

#### Was passiert, wenn mein endpoint ausfällt?

Wenn Ihr webhook endpoint beim Zustellungsversuch des Sync Labs nicht erreichbar ist, geht die Benachrichtigung möglicherweise verloren. Für fehlgeschlagene webhook-Lieferungen gibt es keinen automatischen Wiederholungsversuch. Als Sicherheitsnetz können Sie den Generationsstatus endpoint abfragen, um nach abgeschlossenen oder fehlgeschlagenen Jobs zu suchen, die Ihr webhook möglicherweise übersehen hat.

#### Wie verifiziere ich webhook-Signaturen?

Jede webhook-Anfrage enthält einen Sync-Signature-Header mit einem Zeitstempel und einem HMAC-SHA256-Hash. Verwenden Sie Ihr Signaturgeheimnis von der webhooks-Einstellungsseite, um die erwartete Signatur zu berechnen und sie mithilfe einer zeitsicheren Vergleichsfunktion zu vergleichen, um Timing-Angriffe zu verhindern. Siehe die Codebeispiele oben.