Typebot: Resolvendo Bugs de Deploy e Webhook (Passo a Passo)

Typebot: Resolvendo Bugs de Deploy e Webhook

Se você está com dificuldades para publicar seus fluxos no Typebot, encontrar erros ao salvar alterações, ou se os webhooks simplesmente não disparam, saiba que esses problemas são comuns e geralmente relacionados à configuração do ambiente de hospedagem ou à própria aplicação. Este artigo é focado em ajudar você a diagnosticar e resolver essas questões, garantindo que seu Typebot self-hosted funcione perfeitamente.

Veja a infraestrutura: VPS para Typebot no Brasil para colocar este projeto no ar.

Typebot é uma ferramenta poderosa para criar chatbots interativos e fluxos de conversação. No entanto, como qualquer software self-hosted, ele pode apresentar desafios durante a implantação e operação. Entender os requisitos de servidor e a configuração correta é o primeiro passo para evitar dores de cabeça. Para um funcionamento estável em produção, recomendamos um servidor com no mínimo 4GB de RAM e 2 vCPUs. Este guia prático irá detalhar o processo de deploy e troubleshooting, focando em cenários como build do Typebot travando e falhas de publicação.

Por que o Typebot Não Publica o Fluxo ou o Webhook Falha?

A falha na publicação de fluxos ou no disparo de webhooks no Typebot geralmente se resume a alguns pontos críticos:

1. Recursos Insuficientes do Servidor

O Typebot, especialmente em produção com múltiplos usuários e fluxos complexos, demanda recursos de hardware. A falta de RAM é uma causa comum para o build do Typebot travando ou falhas na publicação. Um servidor com menos de 4GB de RAM pode não conseguir compilar os fluxos adequadamente ou manter os serviços em funcionamento estável. Se você está rodando outros serviços no mesmo VPS, como banco de dados ou um proxy reverso, esses recursos também precisam ser considerados.

2. Configuração do Banco de Dados e Variáveis de Ambiente

O Typebot utiliza um banco de dados (geralmente PostgreSQL) para armazenar fluxos, respostas e configurações. Um banco de dados mal configurado, inacessível ou com problemas de performance pode levar a erros ao salvar fluxos. As variáveis de ambiente, como `DATABASE_URL`, `ADMIN_EMAIL`, `ADMIN_PASSWORD`, `PUBLIC_URL`, entre outras, são cruciais para o funcionamento correto. Um erro em uma delas pode impedir a publicação ou o disparo de webhooks.

3. Problemas com Proxy Reverso e SSL

Se você está acessando o Typebot por um domínio personalizado, um proxy reverso (como Nginx ou Caddy) é essencial. Configurações incorretas no proxy reverso, especialmente relacionadas a limites de tempo de requisição (timeouts) ou problemas com o certificado SSL, podem interromper o processo de publicação ou a comunicação com serviços externos via webhook.

4. Logs e Diagnóstico

A primeira ação em qualquer cenário de erro é consultar os logs. Os logs do Typebot e do seu servidor web (Nginx/Caddy) fornecem pistas valiosas sobre a causa raiz do problema. Erros como `connection refused` ou `timeout` indicam problemas de rede ou serviço indisponível.

Passo a Passo: Implantando Typebot em um VPS Ubuntu

Para garantir uma instalação robusta e resolver os problemas mais comuns, vamos seguir um tutorial de deploy utilizando Docker Compose. Esta abordagem simplifica o gerenciamento de dependências e a escalabilidade.

Pré-requisitos

Você precisará de um servidor VPS rodando Ubuntu (preferencialmente a versão LTS mais recente), com acesso SSH e os pacotes básicos instalados:

• Docker e Docker Compose instalados.
• Um editor de texto (nano, vim).
• Acesso root ou sudo.

Para um ambiente de produção estável, recomendamos um plano com no mínimo 4GB de RAM e 4 vCPUs. Esse é o caso do nosso VPS Brasil Básico, que custa R$ 99/mês e foi validado para rodar essa stack com folga. Se você já usa um VPS com menos recursos, pode enfrentar travamentos, especialmente durante o build do Typebot.

Configuração do Docker Compose

Crie um diretório para o seu projeto Typebot e navegue até ele:

mkdir typebot-deploy
cd typebot-deploy

Crie o arquivo docker-compose.yml com o seguinte conteúdo:

version: '3.8'

services:
  typebot:
    image: 'search.internal.cloud.google.com/google/code-samples/typebot-app:latest'
    container_name: typebot_app
    restart: unless-stopped
    ports:
      - '3000:3000'
    environment:
      # Banco de Dados PostgreSQL
      DATABASE_URL: 'postgresql://user:password@db:5432/typebot?schema=public'
      # Email e Senha do Administrador
      ADMIN_EMAIL: '[email protected]'
      ADMIN_PASSWORD: 'sua_senha_forte'
      # URL Pública onde o Typebot será acessível
      PUBLIC_URL: 'http://localhost:3000' # Ajuste para seu domínio real posteriormente
      # Outras configurações (ajuste conforme necessário)
      NODE_ENV: 'production'
      PORT: 3000
      STRIPE_SECRET_KEY: ''
      STRIPE_PUBLISHABLE_KEY: ''
      POSTHOG_KEY: ''
      GOOGLE_ANALYTICS_ID: ''
      SENTRY_DSN: ''
    depends_on:
      - db

  db:
    image: 'postgres:15'
    container_name: typebot_db
    restart: unless-stopped
    volumes:
      - typebot_db_data:/var/lib/postgresql/data
    environment:
      POSTGRES_DB: 'typebot'
      POSTGRES_USER: 'user'
      POSTGRES_PASSWORD: 'password'

volumes:
  typebot_db_data:

Observação importante: O endereço IP localhost:3000 dentro do container deve ser ajustado para o seu domínio real na variável PUBLIC_URL após configurar o proxy reverso. Se você encontrar o erro typebot não publica o fluxo, verifique se esta variável está correta e aponta para o endereço acessível externamente.

Executando o Typebot

Inicie os containers com o seguinte comando:

docker compose up -d

O comando -d executa os containers em segundo plano. Para verificar o status, use:

docker compose ps

Se o build do Typebot travando for um problema, a primeira verificação é a saída do comando docker compose logs typebot. Se houver erros de memória, é hora de considerar um plano com mais RAM.

Configurando Proxy Reverso (Nginx)

Para acessar seu Typebot externamente de forma segura e com um domínio, configure o Nginx. Crie um arquivo de configuração em /etc/nginx/sites-available/typebot:

server {
    listen 80;
    server_name seu_dominio.com;

    location / {
        proxy_pass http://localhost:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        # Ajuste o timeout para evitar erros de publicação/webhook
        proxy_connect_timeout       600;
        proxy_send_timeout          600;
        proxy_read_timeout          600;
        send_timeout                600;
    }

    # Opcional: Redirecionamento HTTP para HTTPS (após configurar SSL)
    # location / {
    #     return 301 https://$host$request_uri;
    # }
}

Crie um link simbólico e recarregue o Nginx:

sudo ln -s /etc/nginx/sites-available/typebot /etc/nginx/sites-enabled/
sudo nginx -t
sudo systemctl reload nginx

Após configurar o Nginx, lembre-se de atualizar a variável PUBLIC_URL no seu arquivo docker-compose.yml para http://seu_dominio.com (ou https://seu_dominio.com após configurar SSL) e reiniciar os containers com docker compose down && docker compose up -d.

Se os webhooks não disparam, especialmente após configurar o proxy, verifique os logs do Nginx em /var/log/nginx/error.log e /var/log/nginx/access.log para qualquer indício de falha na comunicação com o Typebot.

Typebot: Comparativo de Requisitos e Planos

Escolher o plano de VPS correto é crucial para a estabilidade do Typebot e para evitar problemas de performance e deploy.

Para rodar o Typebot em produção com o build travando devido à falta de recursos, é comum que 2GB de RAM não sejam suficientes. O mínimo recomendado para produção, incluindo o banco de dados PostgreSQL e o proxy reverso Nginx, é de 4GB de RAM. O plano VPS Brasil Básico (R$ 99/mês) oferece exatamente 4GB de RAM e 4 vCPUs, sendo ideal para iniciar com o Typebot.

Erros Comuns ao Configurar Typebot em VPS

Evitar estes erros pode poupar muitas horas de depuração:

1. Variáveis de Ambiente Incorretas

Um erro de digitação em DATABASE_URL ou PUBLIC_URL é o motivo mais frequente para falhas de conexão ou de publicação. Sempre revise essas variáveis com atenção.

2. Porta Já em Uso

Se você tentar rodar o Typebot em uma porta que já está sendo utilizada por outro serviço no seu VPS (como a porta 3000), o container pode falhar ao iniciar. Verifique com sudo netstat -tulnp | grep 3000.

3. Falta de Persistência de Dados

Se você não configurar volumes no Docker Compose para o banco de dados, os dados serão perdidos toda vez que o container for recriado. Isso não é um erro de deploy, mas uma falha de configuração que pode levar à perda de fluxos.

4. Permissões de Arquivo e Diretório

Em cenários mais complexos, permissões incorretas para os volumes do Docker podem impedir a escrita de logs ou dados, causando erros sutis. Certifique-se de que o usuário do Docker tenha as permissões necessárias.

Para aprofundar este tema, consulte também: Typebot: validar webhooks e evitar leads perdidos Typebot: Erros Comuns e Como Resolver em Produção.

Perguntas Relacionadas

O que fazer se o Typebot não salva o fluxo?

Verifique os logs do container do Typebot (docker compose logs typebot) para mensagens de erro. Geralmente, isso indica problemas de conexão com o banco de dados ou variáveis de ambiente mal configuradas, especialmente a DATABASE_URL.

Como resolver o erro "typebot webhook não dispara"?

A causa mais comum é uma configuração incorreta do proxy reverso ou firewall bloqueando a requisição externa. Certifique-se de que a PUBLIC_URL no Typebot esteja correta e que seu Nginx esteja encaminhando as requisições adequadamente. Verifique também os logs do Nginx.

Meu build do Typebot está travando, o que pode ser?

Isso geralmente é um indicativo de recursos de servidor insuficientes. O build do Typebot pode ser intensivo em CPU e RAM. Certifique-se de que seu VPS tenha pelo menos 4GB de RAM para produção. Se o problema persistir, analise os logs para mensagens de erro específicas.

É possível rodar Typebot em um VPS com 2GB de RAM?

Para desenvolvimento e testes, 2GB de RAM podem ser suficientes. No entanto, para produção, onde a estabilidade e a performance são cruciais, 4GB de RAM é o mínimo recomendado. Menos que isso pode levar a travamentos e falhas.

Conclusão e Próximos Passos

Resolver problemas como o typebot não publica o fluxo ou o typebot webhook não dispara exige atenção aos detalhes da configuração do servidor e do próprio Typebot. Ao seguir este guia, você terá um ambiente mais estável e confiável, minimizando erros comuns e garantindo que sua automação funcione sem interrupções.

Se você está pronto para colocar seu Typebot em produção de forma robusta e segura, um VPS adequado é o primeiro passo. A Host You Secure oferece planos otimizados para hospedar suas aplicações self-hosted. Para rodar o Typebot com performance e segurança, recomendamos o plano VPS Brasil Básico, que oferece 4GB de RAM e 4 vCPUs por apenas R$ 99/mês. Esse tutorial foi validado por nós em uma VPS Brasil Básico, garantindo que você tenha a melhor experiência desde o início.

Conheça o VPS Brasil Básico e Implante seu Typebot Agora! por R$ 99/mês