Bloco de Webhook - Receba Chamadas HTTP de Entrada no Fluxo do Seu Chatbot

Pause o fluxo do seu chatbot do ChatMaxima e aguarde uma chamada HTTP externa. Receba cargas, retome o fluxo e envie respostas HTTP personalizadas de volta ao chamador.

Visão Geral

O Bloco de Webhook permite que um sistema externo chame seu chatbot por HTTP. Ele pode ser usado de duas formas: como o primeiro bloco de um fluxo (o próprio webhook inicia a conversa) ou como um bloco no meio do fluxo que pausa a conversa e aguarda um retorno de chamada externo para retomá-la. Em ambos os casos, a carga recebida é analisada e disponibilizada aos blocos seguintes como variáveis. Você pode opcionalmente enviar uma resposta HTTP personalizada de volta ao chamador usando o Bloco de Resposta de Webhook.

Este é o inverso do Bloco de API. O Bloco de API envia requisições de saída. O Bloco de Webhook escuta requisições de entrada. Os casos de uso típicos incluem iniciar uma nova conversa a partir de um evento externo (envio de formulário, criação de registro em CRM, gatilho de iPaaS como n8n ou Zapier), aguardar um retorno de chamada de gateway de pagamento, receber confirmação de entrega de OTP de um provedor de SMS terceiro, ser notificado quando um job de backend de longa duração é concluído ou aceitar atualizações assíncronas de um app externo.

Bloco de Webhook vs. Bloco de API

Aspecto	Bloco de API	Bloco de Webhook
Direção	Saída (o bot chama a API)	Entrada (o sistema externo chama o bot)
Gatilho	Automático quando o fluxo chega ao bloco	Um POST HTTP externo inicia ou retoma o fluxo
Posicionamento	Apenas no meio do fluxo	Primeiro bloco ou no meio do fluxo
Comportamento de Espera	Síncrono, tempo limite de 30 segundos	Inicia o fluxo na chegada, ou pausa o fluxo até a chamada chegar
Uso Típico	Consultar dados, enviar atualizações	Iniciar conversas a partir de eventos externos, aguardar retornos assíncronos
Tratamento da Resposta	Analisa o corpo da resposta em variáveis	A carga recebida se torna variáveis

Onde Encontrá-lo

Abra seu chatbot no Studio
Arraste o bloco Webhook da barra lateral esquerda para o canvas
Coloque-o como o primeiro bloco do seu fluxo (para iniciar uma conversa a partir de um evento externo) ou conecte-o após qualquer bloco anterior (para pausar e aguardar um retorno de chamada no meio do fluxo)
Dê um clique duplo no bloco para configurá-lo

Para enviar uma resposta HTTP personalizada de volta ao chamador, adicione um bloco de Resposta de Webhook imediatamente após o bloco de Webhook.

Webhook como o Primeiro Bloco

Quando o bloco de Webhook é o primeiro bloco do fluxo, ainda não há uma conversa ativa. O POST externo cria a conversa, analisa a carga em variáveis e inicia o fluxo desde o começo. Este é o padrão a usar quando:

Um novo lead é criado no seu CRM e você quer que o bot entre em contato
Um formulário é enviado no seu site e você quer que o bot faça o acompanhamento
Um fluxo de trabalho do n8n, Zapier ou Make aciona uma nova sessão de chat
Um evento de backend (pedido feito, ticket de suporte aberto) deve iniciar uma conversa do bot

Webhook no Meio do Fluxo

Quando o bloco de Webhook é colocado após outro bloco, o fluxo pausa nesse ponto até o POST externo chegar. Este é o padrão a usar quando você precisa repassar a um sistema externo, aguardar sua resposta assíncrona e então continuar o fluxo com base no que ele retornou.

Como Funciona

Modo Primeiro Bloco

External system POSTs to webhook URL
                 │
                 ▼
   New conversation is created
                 │
                 ▼
   Payload parsed into variables
                 │
                 ▼
   Flow starts from the next block
                 │
                 ▼
   Webhook Response sent (optional)

Modo Meio do Fluxo

Bot flow runs ──▶ Reaches Webhook Block ──▶ Flow pauses
                                                  │
                             External system POSTs to webhook URL
                                                  │
                                                  ▼
                            Payload parsed into variables
                                                  │
                                                  ▼
                     Webhook Response sent (optional)
                                                  │
                                                  ▼
                     Flow continues to next block

No modo meio do fluxo, o bot armazena a posição do bloco atual quando pausa. Quando o POST externo chega à URL do webhook, o sistema o associa à conversa pausada, retoma a partir desse bloco e continua adiante.

Configuração

Etapa 1: Coloque o Bloco de Webhook no Fluxo

Arraste o bloco para o canvas no ponto onde o fluxo deve iniciar ou aguardar um evento externo. Por exemplo:

Como o primeiro bloco, para deixar um CRM, formulário ou ferramenta de iPaaS iniciar uma nova conversa de chat
Após capturar detalhes de pagamento, para aguardar a confirmação do gateway de pagamento
Após acionar um job de backend por um bloco de API, para aguardar a notificação de conclusão do job

Etapa 2: Copie a URL do Webhook

Cada bloco de Webhook expõe uma URL única exibida na configuração do bloco. O formato é:

https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/

Passe esta URL ao sistema externo como o destino da requisição POST dele. Para ferramentas de iPaaS (n8n, Zapier, Make), você a cola na etapa HTTP. Para CRMs e construtores de formulários, configure-a como um webhook de saída no painel deles. Para gateways de pagamento e backends assíncronos, defina-a como a URL de retorno ao iniciar o trabalho.

Etapa 3: Autentique o Chamador

A URL do webhook aceita um token Bearer no cabeçalho Authorization. Use o token exibido na configuração do bloco para que o webhook só aceite chamadas de sistemas em que você confia.

curl -X POST https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_token>' \
  --data '{
    "type": "Conversation",
    "channel": "",
    "account_alias": "",
    "reference_id": "",
    "data": {
      "name": ""
    }
  }'

Formato da Carga

Campo	Finalidade
`type`	Tipo de evento, normalmente `Conversation` para iniciar ou retomar um chat
`channel`	Canal que a conversa deve usar (ex.: `whatsapp`, `website`). Deixe vazio para usar o padrão
`account_alias`	Alias da equipe quando o bot é compartilhado entre várias contas
`reference_id`	Identificador externo que você pode usar para vincular a conversa a um registro no seu sistema
`data`	Objeto contendo quaisquer campos que você queira passar como variáveis (ex.: `name`, `email`, `phone`, campos personalizados)

Etapa 4: Referencie os Campos da Carga Recebida

Quando o POST chega, o objeto data é analisado e cada campo se torna uma variável disponível para todos os blocos seguintes.

Para uma carga como:

{
  "type": "Conversation",
  "channel": "whatsapp",
  "reference_id": "ORDER-9981",
  "data": {
    "name": "Priya",
    "phone": "+919000000000",
    "order_id": "ORDER-9981",
    "customer": {
      "email": "priya@example.com"
    }
  }
}

Você pode referenciar:

{name} para Priya
{phone} para +919000000000
{order_id} para ORDER-9981
{customer.email} para campos aninhados
{reference_id} para metadados de nível superior

Etapa 5: Envie e Salve

Clique em Enviar no modal do bloco, depois salve o fluxo usando Salvar Alterações na barra superior.

Bloco de Resposta de Webhook

Combine o bloco de Webhook com um Bloco de Resposta de Webhook quando o chamador espera uma resposta HTTP específica. Sem o bloco de resposta, o bot retorna um 200 OK padrão com {"status":"success"}.

O Bloco de Resposta de Webhook permite personalizar o código de status (ex.: 201, 400, 500), o tipo de conteúdo (application/json, application/xml, text/plain, text/html) e o corpo da resposta enviado de volta ao chamador. Você pode inserir variáveis do fluxo com a sintaxe {variable_name}.

Padrões comuns:

Retornar 201 Created com o novo {conversation_id} para ferramentas de iPaaS
Retornar 400 com um campo de erro quando a carga for inválida
Retornar text/plain OK para retornos de entrega de SMS
Retornar XML para integrações SOAP legadas

Veja a documentação completa do Bloco de Resposta de Webhook para opções de configuração, exemplos e solução de problemas.

Boas Práticas

Sempre valide as cargas recebidas. Use um bloco de Condição após o bloco de Webhook para verificar campos como status == "success" antes de prosseguir
Use o bloco de Resposta de Webhook quando o chamador (gateway de pagamento, provedor de SMS, etc.) espera um formato específico de confirmação. Sem ele, o chamador recebe um 200 OK genérico
Defina um tempo limite significativo em outro lugar. O próprio bloco de Webhook não expira, então combine-o com o Tempo Limite por Inatividade para evitar fluxos que ficam pausados indefinidamente
Proteja a URL do webhook. O token na URL é único por conversa. Não exponha a URL publicamente nem a registre em sistemas que o usuário possa ler
Trate o caso de falha. Ramifique o fluxo com base na carga recebida. Se o evento externo indica falha, envie uma mensagem de recuperação ou roteie para um agente

Casos de Uso Comuns

Lead de CRM Cria uma Conversa (Primeiro Bloco)

Um novo lead é adicionado no seu CRM, e o bot abre uma conversa de WhatsApp para qualificá-lo.

Bloco de Webhook (primeiro bloco): O CRM envia (POST) a carga do lead com phone, name, source
Bloco de Mensagem: Hi {name}, thanks for your interest!
Bloco de Pergunta: Faça perguntas de qualificação
Bloco de API: Envie os dados qualificados de volta ao CRM

Gatilho de n8n ou Zapier (Primeiro Bloco)

Uma ferramenta de automação dispara um webhook quando um evento específico acontece (novo pedido na Shopify, envio de Typeform, etc.), e o bot faz o acompanhamento com o cliente.

Bloco de Webhook (primeiro bloco): O n8n envia (POST) {"phone":"...", "order_id":"..."}
Bloco de Mensagem: Your order {order_id} has shipped!

Retorno de Chamada de Gateway de Pagamento

O usuário inicia o pagamento, o bot o envia para uma página de pagamento e então aguarda o gateway enviar (POST) o resultado.

Bloco de API: Crie a sessão de pagamento, armazene payment_url
Bloco de Mensagem: Envie payment_url ao usuário
Bloco de Webhook: Pause o fluxo, passe a URL do webhook ao gateway como retorno de chamada
Bloco de Condição: Ramifique em {status} == "success"
Bloco de Resposta de Webhook: Retorne {"received":true} ao gateway

Notificação de Job Assíncrono

O bot aciona um job de geração de relatório de longa duração, aguarda a conclusão e então envia o link do relatório ao usuário.

Bloco de API: Envie o job, armazene job_id, inclua a URL do webhook como retorno de chamada
Bloco de Mensagem: "Gerando seu relatório, isso pode levar um minuto..."
Bloco de Webhook: Aguarde o retorno de chamada de conclusão do job
Bloco de Mensagem: Your report is ready: {report_url}

Status de Entrega de OTP de Terceiros

O bot envia um OTP por um provedor de SMS externo que usa webhooks para confirmar a entrega.

Bloco de API: Acione o envio do OTP, passe a URL do webhook
Bloco de Webhook: Aguarde o status de entrega
Bloco de Condição: Ramifique em {delivery_status}
Bloco de Mensagem: Peça o código OTP ou peça desculpas pela falha na entrega

Envio de Formulário Externo

Um app web separado coleta informações extras e as envia (POST) ao bot quando o usuário termina.

Bloco de Mensagem: Envie a URL do formulário ao usuário
Bloco de Webhook: Aguarde o envio do formulário
Bloco de Mensagem: Thanks, we received your {form_field}

Solução de Problemas

O fluxo está travado no bloco de Webhook (meio do fluxo)

Confirme que o sistema externo realmente enviou (POST) à URL do webhook. Verifique os logs de entrega dele
Verifique se a URL é acessível pelo sistema externo (não bloqueada por firewall ou lista de IPs permitidos)
Certifique-se de que a URL inclui o caminho completo e o token final
Combine com o Tempo Limite por Inatividade para fechar automaticamente conversas que nunca recebem o retorno de chamada

O webhook de primeiro bloco não está iniciando uma conversa

Confirme que o bloco de Webhook é o primeiro bloco do fluxo (nenhum outro bloco se conecta a ele)
Verifique se a carga inclui um identificador do destinatário (telefone, e-mail ou ID de visitante) que o bot possa usar para criar a conversa
Verifique se o bot está publicado e se o canal (WhatsApp, widget do site, etc.) está conectado
Inspecione o status de resposta retornado ao chamador. Um 4xx indica que a carga foi rejeitada

Os campos da carga recebida estão vazios nos blocos seguintes

Confirme que o Content-Type do POST recebido é application/json ou um tipo de formulário suportado
Verifique os nomes exatos dos campos na carga. Os nomes das variáveis são sensíveis a maiúsculas
Para campos aninhados, use a notação de ponto: {customer.email}, não {customer_email}
Inspecione a carga recebida bruta no registro da conversa para ver o que foi realmente recebido

O chamador recebe um `200 OK` genérico em vez da minha resposta personalizada

Certifique-se de ter adicionado um bloco de Resposta de Webhook após o bloco de Webhook
Verifique se o bloco de resposta é alcançável no grafo do fluxo. Um bloco de Condição pode estar desviando dele
Verifique novamente se o botão Enviar foi clicado e o fluxo foi salvo

O sistema externo rejeita a resposta do webhook

Confirme que o Content-Type corresponde ao que o chamador espera (por exemplo, application/json vs text/plain)
Valide se o corpo da resposta está bem formado. Um objeto JSON não fechado fará com que chamadores rigorosos tentem novamente
Verifique o código de status HTTP. Alguns chamadores aceitam apenas 200, não 201 ou 202

Múltiplos POSTs chegam para a mesma conversa

Alguns sistemas externos tentam novamente os webhooks se acharem que a primeira entrega falhou. A URL do webhook é idempotente por conversa, então apenas o primeiro POST válido retoma o fluxo. Os POSTs subsequentes recebem a resposta configurada sem avançar o fluxo novamente.

Próximas Etapas

Bloco de Resposta de Webhook - Envie respostas HTTP personalizadas de volta ao chamador
Bloco de API - Chame APIs externas a partir do fluxo
Tempo Limite por Inatividade - Feche automaticamente conversas que ficam pausadas por muito tempo
Bloco de Fim de Conversa - Encerre conversas manualmente com um botão de reinício
Visão Geral do Studio - Explore todos os tipos de bloco e os recursos do construtor de fluxos