Webhooks

Sync Labs webhooks fornece notificações POST HTTP em tempo real quando seus trabalhos de geração lip sync são concluídos ou falham. Use webhooks em vez de sondagem para criar fluxos de trabalho eficientes e orientados a eventos que respondam às mudanças de status de geração sem chamadas API repetidas.

Como configuro o webhooks?

Para utilizar webhooks:

1. Especifique um parâmetro webhookUrl ao chamar um API endpoint que o suporte.
2. Certifique-se de que seu webhook endpoint possa receber e lidar com solicitações HTTP POST e possa consumir a [carga útil do Webhook para atualizações de status] (/api-reference/api/webhooks-payload-reference/webhooks).

Ao aproveitar o webhooks, você pode agilizar seu fluxo de trabalho com chamadas sem bloqueio, permitindo que você se concentre em outras tarefas enquanto recebe notificações de conclusão de trabalhos. Se você não estiver recebendo eventos, confirme se o webhookUrl exato foi incluído na solicitação de geração, o endpoint pode ser acessado publicamente por meio de HTTPS e retorna uma resposta 2xx às solicitações POST rapidamente. Se a entrega for perdida porque seu endpoint está indisponível ou rejeitou a solicitação, pesquise o status de geração endpoint como substituto.

Quando os webhooks são enviados?

Um webhook de geração é enviado quando a geração chega a um status final: COMPLETED, FAILED ou REJECTED. Um webhook de batch é enviado quando o batch fica COMPLETED ou FAILED.

Cada solicitação traz estes cabeçalhos:

Novas tentativas e duplicatas

A Sync tenta novamente os webhooks que o seu endpoint não aceitou, tanto de gerações quanto de batches:

• Até 6 tentativas ao longo de cerca de 2 horas. As novas tentativas esperam aproximadamente 1, 3, 9, 27 e 60 minutos (±25% de variação).
• O que é repetido: timeouts, erros de conexão e respostas 429 e 5xx. Um cabeçalho Retry-After nessas respostas substitui a espera calculada (entre 1 segundo e 60 minutos).
• O que não é repetido: qualquer outra resposta 4xx, incluindo 408, uma URL inválida ou um redirecionamento diferente de 307/308. A entrega para na primeira resposta desse tipo.
• Timeout: cada tentativa espera até 10 segundos pela sua resposta. Retorne 2xx imediatamente e faça o trabalho demorado depois.
• Destinos: a URL precisa resolver para um endereço público. São seguidos até três redirecionamentos 307/308.

Uma nova tentativa pode chegar depois que o seu endpoint já processou o evento, por exemplo quando a sua resposta 2xx passou do timeout, então trate duplicatas. Elimine duplicatas pelo cabeçalho Sync-Delivery-Id ou pelo id da geração ou do batch no payload. Cada tentativa é assinada de novo com um novo timestamp, então o valor de Sync-Signature muda entre tentativas da mesma entrega.

Se todas as tentativas falharem, o evento não é enviado de novo. Consulte Get Generation ou Get Batch para recuperar os resultados perdidos.

Tratamento de erros em webhooks

O payload do webhook de geração tem os mesmos campos que Get Generation para id, createdAt, status, model, input, webhookUrl, options e outputUrl, além de synthesizedAudioUrl nas gerações que usaram uma entrada de texto. Quando uma geração falha ou é rejeitada, dois campos explicam o motivo; nos demais casos, ambos são null:

• error: uma mensagem de erro legível descrevendo o que deu errado
• errorCode: um código de erro legível por máquina para o tratamento programático de erros (consulte o Guia de tratamento de erros e GET /v2/errors para a lista completa)

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

Baseie a lógica em errorCode, não no texto da mensagem. Veja a referência do payload para todos os campos.

Verifique as assinaturas webhook

Para garantir que as solicitações webhook sejam provenientes de Sync Labs, assinamos cada solicitação webhook com uma assinatura. A assinatura está incluída no cabeçalho Sync-Signature.

Para verificar assinaturas, use seu segredo de assinatura. Você também pode recuperá-lo programaticamente com GET /v2/organizations/webhook/secret. Guarde o valor completo whsec_... com segurança; masked=true serve apenas para exibição e não deve ser usado na verificação.

O cabeçalho tem a forma t=<timestamp>,v1=<assinatura>:

• t: o horário Unix, em segundos, em que esta tentativa foi enviada
• v1: o HMAC-SHA256 em hex de <t>.<corpo bruto da solicitação>, com o seu segredo de assinatura como chave

Calcule o HMAC sobre os bytes exatos que você recebeu, não sobre um JSON serializado de novo. Para limitar repetições, você também pode rejeitar solicitações cujo t esteja longe do seu horário atual; deixe alguns minutos de margem para diferenças de relógio.

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 - Processamento em batch — use webhooks com processamento batch para fluxos de trabalho de alto volume - Limites de taxa - entenda API rate limiting e como isso afeta a entrega de webhook

Perguntas frequentes