> For the documentation index, fetch https://sync.so/docs/llms.txt. Append .md to a page URL for Markdown. Documentation-search MCP: https://sync.so/docs/_mcp/server.

# Webhooks

> Configure webhooks para atualizações de status de geração lip sync em tempo real. Inclui verificação de assinatura, tratamento de erros e exemplos de código.

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).

> **Note**
>
> Por motivos de segurança, seu webhook URL deve ser configurado para aceitar e
> processar solicitações HTTPS `POST`.

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](/developer-guides/error-handling) 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](https://sync.so/settings/webhooks). Você também pode recuperá-lo programaticamente com [`GET /v2/organizations/webhook/secret`](/api-reference/api/organizations-api/get-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)

**`Javascript`**

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

**`Python`**

```python Python
import hmac
import hashlib
import re
from flask import Flask, request, jsonify

app = Flask(__name__)

WEBHOOK_SECRET = 'whsec_'


def verify_signature(raw_body: bytes, signature: str, webhook_secret: str) -> bool:
    if not signature:
        return False

    try:
        match = re.match(r't=(\d+),v1=(.+)', signature)
        if not match:
            return False

        timestamp, received_signature = match.groups()
        if not timestamp or not received_signature:
            return False

        expected_signature = hmac.new(
            webhook_secret.encode("utf-8"),
            timestamp.encode("utf-8") + b"." + raw_body,
            hashlib.sha256
        ).hexdigest()

        # Timing-safe comparison to prevent timing attacks
        return hmac.compare_digest(received_signature, expected_signature)
    except Exception:
        return False


@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('Sync-Signature')

    if not verify_signature(request.get_data(cache=True), signature, WEBHOOK_SECRET):
        return jsonify({'message': 'Invalid signature'}), 400

    return jsonify({'message': 'Webhook signature verified'}), 200


if __name__ == "__main__":
    app.run(host='0.0.0.0', port=8085)

```

## Perguntas frequentes

#### Como faço para testar o webhooks localmente?

Use uma ferramenta de tunelamento como o ngrok para expor seu servidor local à Internet. Inicie seu webhook endpoint localmente e execute o ngrok para obter um HTTPS URL público. Passe esse URL como webhookUrl ao criar uma geração. Sync Labs enviará solicitações POST ao seu servidor local através do túnel.

#### E se meu endpoint estiver inoperante?

Se o seu webhook endpoint estiver inacessível quando o Sync Labs tentar a entrega, a notificação poderá ser perdida. Não há nova tentativa automática para entregas webhook com falha. Como rede de segurança, você pode pesquisar o status de geração endpoint para verificar trabalhos concluídos ou com falha que seu webhook possa ter perdido.

#### Como verifico as assinaturas webhook?

Cada solicitação webhook inclui um cabeçalho Sync-Signature contendo um carimbo de data/hora e um hash HMAC-SHA256. Use seu segredo de assinatura na página de configurações do webhooks para calcular a assinatura esperada e compará-la usando uma função de comparação segura de tempo para evitar ataques de temporização. Veja os exemplos de código acima.