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.

Quand les webhooks sont-ils envoyés?

Un webhook de génération est envoyé quand la génération atteint un statut final : COMPLETED, FAILED ou REJECTED. Un webhook de batch est envoyé quand le batch est COMPLETED ou FAILED.

Chaque requête contient ces headers :

Relances et doublons

Sync relance les webhooks que votre endpoint n’a pas acceptés, pour les générations comme pour les batches :

• Jusqu’à 6 tentatives sur environ 2 heures. Les relances attendent environ 1, 3, 9, 27 et 60 minutes (±25 % d’aléa).
• Ce qui est relancé : les timeouts, les erreurs de connexion et les réponses 429 et 5xx. Un header Retry-After sur ces réponses remplace le délai calculé (entre 1 seconde et 60 minutes).
• Ce qui n’est pas relancé : toute autre réponse 4xx, y compris 408, une URL invalide ou une redirection autre que 307/308. La livraison s’arrête à la première réponse de ce type.
• Timeout : chaque tentative attend votre réponse jusqu’à 10 secondes. Renvoyez 2xx immédiatement et faites le travail long ensuite.
• Destinations : l’URL doit résoudre vers une adresse publique. Jusqu’à trois redirections 307/308 sont suivies.

Une relance peut arriver après que votre endpoint a déjà traité l’événement, par exemple quand votre réponse 2xx a dépassé le timeout : gérez donc les doublons. Dédupliquez avec le header Sync-Delivery-Id, ou avec l’id de la génération ou du batch dans le payload. Chaque tentative est signée à nouveau avec un nouveau timestamp, donc la valeur de Sync-Signature change entre les tentatives d’une même livraison.

Si toutes les tentatives échouent, l’événement n’est plus renvoyé. Interrogez Get Generation ou Get Batch pour récupérer les résultats manqués.

Gestion des erreurs dans les webhooks

Le payload du webhook de génération contient les mêmes champs que Get Generation pour id, createdAt, status, model, input, webhookUrl, options et outputUrl, ainsi que synthesizedAudioUrl pour les générations qui ont utilisé une entrée texte. Quand une génération échoue ou est rejetée, deux champs en donnent la raison ; sinon, les deux valent null :

• error : message d’erreur lisible par un humain, décrivant ce qui a échoué
• errorCode : code d’erreur lisible par une machine, pour une gestion programmatique (voir le guide gestion des erreurs et GET /v2/errors pour la liste complète)

{
  "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"
}

Basez votre logique sur errorCode, pas sur le texte du message. Voir la référence du payload pour tous les champs.

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. Conservez la valeur complète whsec_... en lieu sûr ; masked=true sert uniquement à l’affichage et ne doit pas être utilisé pour la vérification.

Le header a la forme t=<timestamp>,v1=<signature> :

• t : l’heure Unix, en secondes, à laquelle cette tentative a été envoyée
• v1 : le HMAC-SHA256 en hex de <t>.<body brut de la requête>, avec votre signing secret comme clé

Calculez le HMAC sur les octets exacts reçus, pas sur du JSON resérialisé. Pour limiter les rejeux, vous pouvez aussi refuser les requêtes dont t est éloigné de votre heure actuelle ; laissez quelques minutes de marge pour le décalage d’horloge.

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