Webhooks

Los webhooks de Sync Labs entregan notificaciones HTTP POST en tiempo real cuando tus jobs de generación de lip sync se completan o fallan. Usa webhooks en lugar de polling para construir flujos de trabajo eficientes y orientados a eventos que respondan a cambios de estado sin llamadas repetidas a la API.

¿Cómo configuro webhooks?

Para utilizar webhooks:

1. Especifica un parámetro webhookUrl al llamar a un endpoint de API que lo soporte.
2. Asegúrate de que tu endpoint de webhook pueda recibir y manejar requests HTTP POST y pueda consumir el Webhook Payload para actualizaciones de estado.

Al aprovechar webhooks, puedes simplificar tu flujo con llamadas no bloqueantes, lo que te permite enfocarte en otras tareas mientras recibes notificaciones de finalización de jobs.

Si no recibes eventos, confirma que se incluyó exactamente webhookUrl en el request de generación, que el endpoint sea públicamente accesible por HTTPS y que devuelva una respuesta 2xx rápidamente a requests POST. Si la entrega falla porque tu endpoint no está disponible o rechaza el request, haz polling del endpoint de estado de generación como fallback.

Manejo de errores en webhooks

Cuando una generación falla, el payload del webhook incluirá información de error en dos campos:

• error: un mensaje de error legible por humanos que describe qué salió mal
• error_code: un código de error específico que puede usarse para manejo programático de errores (consulta la guía de manejo de errores para ver una lista completa de códigos)

Esta estructura de errores mejorada te permite tanto mostrar mensajes significativos a los usuarios como implementar lógica de manejo específica basada en códigos de error.

Verifica firmas de webhook

Para asegurar que los requests de webhook provengan de Sync Labs, firmamos cada request con una firma. La firma se incluye en el header Sync-Signature.

Para verificar firmas, usa tu signing secret. También puedes obtenerlo programáticamente con GET /v2/organizations/webhook/secret. Guarda de forma segura el valor completo whsec_...; masked=true es solo para visualización y no debe usarse para verificación.

La firma está compuesta por 2 componentes:

• Timestamp (al momento de enviar el evento)
• Hash de firma (el timestamp y el cuerpo JSON raw exacto del request)

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

Recursos relacionados

• procesamiento por lotes — usa webhooks con procesamiento por lotes para flujos de alto volumen
• Rate Limits — comprende el rate limiting de la API y cómo afecta la entrega de webhooks

Preguntas frecuentes