Typebot: validar webhooks e evitar leads perdidos

Resposta rápida

Antes de publicar um Typebot, envie respostas fictícias para um endpoint de homologação e valide o payload recebido. O endpoint deve responder rápido, registrar um identificador do evento e encaminhar o trabalho pesado para uma fila ou processo separado. Só depois ligue a integração ao CRM, WhatsApp ou checkout real.

Veja a infraestrutura: planos de VPS da You Secure para colocar este projeto no ar.

Desenhe o contrato do lead

Liste campos obrigatórios, formato, tamanho e regras de privacidade. Um telefone pode vir com máscara; um e-mail pode ter espaços. Normalize no consumidor, mas preserve o payload original somente quando isso for necessário e permitido. Não registre tokens ou dados sensíveis em texto puro.

Faça um endpoint de teste

curl -i -X POST https://automacao.exemplo.com/typebot/test \
  -H 'Content-Type: application/json' \
  -H 'X-Request-ID: tb-test-001' \
  --data '{"event":"lead.created","lead_id":"tb-test-001","email":"[email protected]"}'

Use dados artificiais. Registre status, horário, request ID e resposta. 2xx confirma aceite HTTP, não a entrega final ao CRM.

Valide, persista e responda

O consumidor deve validar assinatura/autorização, esquema e campos mínimos. Depois grave uma entrada idempotente usando lead_id ou outro identificador único. Responda em poucos segundos e processe notificações em background. Se o mesmo evento chegar de novo, a segunda execução deve ser segura.

Investigue falhas por camada

Falha de DNS ou TLS acontece antes da aplicação. 401/403 aponta credencial ou política. 400 normalmente é contrato inválido. 429 exige backoff; 5xx exige logs no servidor e retry com limite. Correlacione os logs do Typebot, proxy e consumidor pelo request ID.

Proteja a conversão

Monitore taxa de webhooks aceitos, rejeitados, retries e idade da fila. Crie alerta para eventos sem processamento, não apenas para servidor fora do ar. Nunca envie um lead duplicado ao vendedor por causa de um retry.

Para uma integração contínua, veja a VPS para Typebot e mantenha o endpoint atrás de HTTPS, autenticação e firewall.

Checklist

• [ ] Payload e campos obrigatórios documentados.
• [ ] Endpoint de homologação testado.
• [ ] Dados fictícios usados no teste.
• [ ] Resposta rápida e processamento assíncrono.
• [ ] Idempotência e retry com limite.

FAQ

O Typebot deve esperar o CRM terminar?

Não necessariamente. Aceite o evento com segurança e processe a integração em segundo plano quando ela for demorada.

O que fazer com um webhook inválido?

Registre o motivo sem expor dados sensíveis, responda com status adequado e envie para uma fila de análise se a recuperação for possível.

Critérios antes de ativar

Um fluxo está pronto quando um evento válido chega ao destino, um evento repetido não duplica o lead, um payload inválido é rejeitado com motivo observável e uma indisponibilidade temporária entra em retry controlado. Teste também cancelamento e timeout; o usuário não deve ficar preso esperando um CRM externo. Registre a versão do Typebot e do consumidor junto do resultado para que uma mudança posterior possa ser comparada.