Webhooks

Les webhooks Sync Labs envoient des notifications HTTP POST en temps réel quand vos jobs de génération lip sync se terminent ou échouent. Utilisez les webhooks au lieu du polling pour créer des workflows efficaces orientés événements qui réagissent aux changements de statut sans appels API répétés.

Comment configurer les webhooks?

Pour utiliser les webhooks:

1. Spécifiez un paramètre webhookUrl lorsque vous appelez un endpoint API qui le prend en charge.
2. Assurez-vous que votre endpoint webhook peut recevoir et traiter les requêtes HTTP POST, et consommer le Webhook Payload des mises à jour de statut.

En exploitant les webhooks, vous simplifiez votre workflow avec des appels non bloquants, ce qui vous permet de vous concentrer sur d’autres tâches tout en recevant les notifications de fin de job.

Si vous ne recevez pas d’événements, confirmez que la valeur exacte webhookUrl a bien été incluse dans la requête de génération, que l’endpoint est publiquement accessible en HTTPS, et qu’il renvoie rapidement une réponse 2xx aux requêtes POST. Si la livraison est manquée parce que votre endpoint est indisponible ou rejette la requête, interrogez l’endpoint de statut de génération comme solution de repli.

Gestion des erreurs dans les webhooks

Quand une génération échoue, le payload webhook inclut les informations d’erreur dans deux champs:

• error: message d’erreur lisible par un humain, décrivant ce qui a échoué
• error_code: code d’erreur spécifique, utilisable pour une gestion programmatique (voir le guide gestion des erreurs pour la liste complète)

Cette structure d’erreur améliorée vous permet à la fois d’afficher des messages utiles aux utilisateurs et d’implémenter une logique de gestion spécifique selon les codes d’erreur.

Vérifier les signatures webhook

Pour garantir que les requêtes webhook proviennent de Sync Labs, nous signons chaque requête webhook. La signature est incluse dans le header Sync-Signature.

Pour vérifier les signatures, utilisez votre signing secret. Vous pouvez aussi le récupérer de façon programmatique avec GET /v2/organizations/webhook/secret. Stockez la valeur complète whsec_... de façon sécurisée, masked=true est uniquement destiné à l’affichage et ne doit pas être utilisé pour la vérification.

La signature est composée de 2 éléments:

• Timestamp (au moment de l’envoi de l’événement)
• Hash de signature (le timestamp et le body JSON brut exact de la requête)

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

Ressources associées

• traitement par lots — utilisez les webhooks avec le traitement par lots pour les workflows à haut volume
• Rate Limits — comprendre le rate limiting API et son impact sur la livraison webhook

Questions fréquentes