Webhooks e Notificações

Configure notificações automáticas em tempo real sobre suas transcrições. Aprenda como configurar webhooks, implementar segurança e integrar com seus sistemas.

Por Que Usar Webhooks?

Eventos Disponíveis

| Evento | Descrição | Payload | |---|---|---| | transcription.started | Transcrição iniciou processamento | Upload ID, engine, timestamp | | transcription.progress | Progresso atualizado | Upload ID, porcentagem, estimativa | | transcription.completed | Transcrição concluída com sucesso | Upload ID, texto, duração, créditos | | transcription.failed | Transcrição falhou | Upload ID, erro, tipo do erro | | transcription.retry | Tentativa de retry iniciada | Upload ID, tentativa, engine | | upload.completed | Upload de arquivo concluído | Upload ID, tamanho, formato | | credits.low | Créditos abaixo do limite configurado | Saldo atual, limite |

Configuração Passo a Passo

Exemplos de Implementação

Node.js (Express)

const express = require('express');
const crypto = require('crypto');

const app = express();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

app.post('/webhook/vozparatexto', express.raw({ type: 'application/json' }), (req, res) => {
  // Verificar assinatura
  const signature = req.headers['x-webhook-signature'];
  const hash = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (signature !== hash) {
    return res.status(401).send('Assinatura inválida');
  }

  const event = JSON.parse(req.body);

  switch (event.type) {
    case 'transcription.completed':
      console.log('Transcrição concluída:', event.data.uploadId);
      // Processar resultado
      break;
    case 'transcription.failed':
      console.log('Transcrição falhou:', event.data.error);
      // Tratar erro
      break;
  }

  res.status(200).json({ received: true });
});

Python (Flask)

import hmac
import hashlib
from flask import Flask, request, jsonify

app = Flask(__name__)
WEBHOOK_SECRET = os.environ['WEBHOOK_SECRET']

@app.route('/webhook/vozparatexto', methods=['POST'])
def handle_webhook():
    # Verificar assinatura
    signature = request.headers.get('X-Webhook-Signature')
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        request.data,
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        return jsonify({'error': 'Assinatura inválida'}), 401

    event = request.json

    if event['type'] == 'transcription.completed':
        process_transcription(event['data'])
    elif event['type'] == 'transcription.failed':
        handle_failure(event['data'])

    return jsonify({'received': True}), 200

Segurança e Melhores Práticas

Boas práticas de segurança:

• Valide a assinatura HMAC-SHA256 de cada requisição
• Use HTTPS no endpoint de recebimento
• Implemente idempotência (mesmo evento processado apenas uma vez)
• Rotacione o webhook secret periodicamente
• Registre todos os eventos recebidos para auditoria

Boas práticas de implementação:

• Responda com 200 OK rapidamente (dentro de 5 segundos)
• Processe eventos de forma assíncrona
• Implemente fila de processamento para alta carga
• Monitore falhas de entrega no dashboard

Mecanismo de Retry

Quando seu endpoint não responde com sucesso (2xx), o VozParaTexto tenta reenviar:

| Tentativa | Intervalo | Descrição | |---|---|---| | 1 | Imediato | Primeira tentativa | | 2 | 1 minuto | Após falha inicial | | 3 | 5 minutos | Segunda retentativa | | 4 | 30 minutos | Terceira retentativa | | 5 | 2 horas | Última tentativa |

Após 5 falhas consecutivas, o webhook é automaticamente desativado e você recebe uma notificação por email.

Solução de Problemas

Webhook não está sendo recebido

Possíveis causas: URL incorreta, firewall bloqueando, certificado SSL inválido.

Soluções: Verifique a URL no dashboard, libere o IP do VozParaTexto no firewall, valide seu certificado SSL.

Assinatura inválida

Possíveis causas: Secret incorreto, encoding do body diferente, middleware alterando o body.

Soluções: Confirme o secret no dashboard, use raw body para verificação, desative middleware de parsing antes da verificação.

Eventos duplicados

Possíveis causas: Retry após timeout, resposta lenta do seu servidor.

Soluções: Implemente idempotência usando o event.id, responda 200 OK rapidamente, processe assincronamente.

Continue aprendendo

• Integração via API - Documentação completa da API
• Automação de Fluxos - Automatize processos com webhooks
• Processamento em Lote - Transcreva múltiplos arquivos