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.

Tratamento de erros em webhooks

Quando uma geração falha, a carga webhook incluirá informações de erro em dois campos: - error: Uma mensagem de erro legível descrevendo o que deu errado - error_code: Um código de erro específico que pode ser usado para tratamento de erros programáticos (consulte o Guia de tratamento de erros para obter uma lista completa de códigos de erro) Essa estrutura de erro aprimorada permite exibir mensagens significativas aos usuários e implementar uma lógica específica de tratamento de erros com base nos códigos de erro.

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. Armazene o valor whsec_... completo com segurança; masked=true é apenas para exibição e não deve ser usado para verificação. A assinatura é composta por 2 componentes: - Timestamp (no momento do envio do evento) - Hash de assinatura (o carimbo de data/hora e o corpo exato da solicitação JSON)

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