Bloco Webhook: mande os dados da conversa para outro sistema

O bloco Webhook pega os dados da conversa (nome, telefone, usuário do teste, plano escolhido) e manda para um sistema de fora: n8n, Zapier, Make ou uma API sua. O que esse sistema responder fica guardado em variáveis. Num negócio de assinatura, é o jeito de registrar cada contato numa planilha, avisar outro sistema que a venda fechou ou consultar um cadastro que só existe fora do Flow Gestor.

O que o bloco Webhook faz

O Webhook é um bloco de bastidor (o cartão traz essa palavrinha no cabeçalho): o cliente não vê nada quando ele roda. O servidor do Flow Gestor chama o endereço que você informou, espera a resposta e segue. Em ordem:

1. Cada campo tem as variáveis trocadas pelo valor real: {primeiro_nome} vira "Carla". O mesmo vale para o endereço e para o valor dos cabeçalhos.
2. A chamada sai por "POST" (os campos vão em JSON) ou por "GET" (os campos vão no endereço).
3. O bot espera a resposta por até 10 segundos.
4. A resposta vira variáveis: {webhook_status} com o código HTTP e, se veio um JSON, um {webhook_campo} para cada dado simples dele.
5. A conversa segue pela saída "Enviou" ou pela saída "Falhou".

Na paleta, ele fica no grupo "Ações", ao lado do bloco Ação e do bloco Etiqueta. Se ainda não conhece o quadro, comece por Como funciona o chatbot.

Quando usar (e quando usar outro bloco)

Use o Webhook quando algo precisa acontecer fora daqui: registrar o contato numa planilha assim que ele pedir o teste grátis, avisar outro sistema que a venda fechou, consultar um cadastro seu que não está no Flow Gestor.

Antes de arrastar o Webhook, veja se outro bloco já resolve:

• Criar o teste, gerar a fatura, buscar os dados do cliente ou mostrar os planos é trabalho do bloco Ação, sem chamada externa.
• Lembrar de algo sobre a pessoa (de onde veio, se já recebeu oferta) é trabalho do bloco Etiqueta.
• Decidir o caminho com base numa informação é trabalho do bloco Condição.

Regra prática: informação que nasce aqui dentro, Ação. Informação que vai para fora ou vem de fora, Webhook.

Como configurar, campo a campo

Clique no cartão e o painel da direita abre com quatro seções: "Endereço", "Campos enviados", "Cabeçalhos" e "Resposta". Não existe botão de salvar: cada letra já fica guardada, e o indicador no alto do quadro mostra "Salvo".

"Endereço": a URL que vai receber os dados. A dica embaixo diz tudo: "Precisa ser https. Endereço interno ou de rede local é recusado." Se o texto não começar com https://, o campo fica vermelho com o aviso "O endereço precisa começar com https://". O exemplo sugerido é https://n8n.seudominio.com/webhook/contatos. O endereço também aceita variável entre chaves.

"Método": "POST" manda os campos em JSON; "GET" manda os campos no endereço. O bloco nasce em POST, que é o que n8n, Zapier e Make esperam.

"Campos enviados": o corpo da chamada, um campo por linha. O bloco já nasce com uma linha em branco, para mostrar o formato. O botão "Campo" adiciona outra; a lixeira remove. À esquerda vai o nome (o exemplo mostra "nome"), à direita o valor (o exemplo mostra {primeiro_nome}). O contador diz "Nenhum campo" ou quantas linhas existem, em branco ou não. O valor aceita qualquer variável do fluxo: {telefone}, {teste_usuario}, {fatura_link} ou a resposta de uma Pergunta sua. A relação completa está em Variáveis. Linha sem nome e sem valor é ignorada no envio; linha com valor e sem nome vira pendência.

"Cabeçalhos": começa recolhida, com o resumo "nenhum". O texto avisa: "Opcional. No POST o Content-Type já vai sozinho." O botão "Cabeçalho" adiciona uma linha com nome (o exemplo mostra "Authorization") e valor. Use quando o sistema de fora exige um token, e leia o aviso do painel: "Cabeçalho com token fica gravado no fluxo como texto. Prefira um token só para este webhook, que possa ser trocado sem afetar mais nada."

"Guardar a resposta em (opcional)", na seção "Resposta": o prefixo das variáveis que a resposta cria. Com "n8n" você ganha {n8n_status} e um {n8n_campo} para cada dado simples que o sistema devolver. Vazio, o prefixo é "webhook". O bot aproveita só o primeiro nível do JSON e só valores simples (texto, número, verdadeiro ou falso), com o nome em minúsculo e cada valor cortado em 500 caracteres. Resposta sem JSON, tipo um "OK", não é erro: você fica só com o status.

Configurado, o cartão mostra o método e o domínio ("POST · n8n.seudominio.com"), a quantidade de campos com nome (ou "sem campos no corpo") e, se você preencheu o prefixo, "resposta em" seguido dele. Sem endereço, ele mostra "Informe o endereço que vai receber" em itálico.

As saídas e como ligar

O cartão tem duas bolinhas na direita:

• "Enviou": o sistema de fora respondeu com sucesso (código HTTP de 200 a 299).
• "Falhou": qualquer outra coisa. Endereço sem https ou de rede interna, sem resposta em 10 segundos, redirecionamento (o bot não segue, por segurança) ou erro HTTP como 404 e 500.

Ligue as duas. "Falhou" é obrigatória: sem ela o fluxo nem publica, porque serviço de fora cai, e no dia em que o n8n estiver fora a conversa morreria calada. "Enviou" solta não impede a publicação, mas gera aviso: a conversa encerra em silêncio ali.

As variáveis da resposta são gravadas antes de o bot escolher a saída. No caminho "Falhou", {n8n_status} existe quando o sistema respondeu com erro (um 500), mas não quando não houve resposta nenhuma (tempo esgotado, endereço recusado). Use essa variável numa Condição, nunca num texto que o cliente lê.

Exemplo prático: a PlayHub registra quem pediu teste

A PlayHub vende assinatura e quer que todo contato que pedir o teste grátis caia numa planilha, via n8n, com usuário e vencimento. O desenho:

1. Início ligado a um bloco de Botões: "Oi, {saudacao}! Aqui é a PlayHub. O que você precisa?" com [Quero testar] e [Já sou cliente].
2. "Quero testar" ligado a uma Pergunta: "Como você se chama?", guardando em nome.
3. "Respondeu certo" ligado a uma Ação "Criar teste".
4. "Deu certo" ligado ao Webhook, configurado assim:
   • "Endereço": https://n8n.playhub.com.br/webhook/testes, "Método": "POST"
   • "Campos enviados": nome = {primeiro_nome}, telefone = {telefone}, usuario = {teste_usuario}, vencimento = {teste_vencimento}
   • "Cabeçalhos": Authorization = Bearer mais o token criado no n8n só para este webhook
   • "Guardar a resposta em (opcional)": n8n
5. "Enviou" e "Falhou" ligados ao mesmo bloco de Mensagem: "Seu teste começou, {primeiro_nome}! Usuário: {teste_usuario} · Senha: {teste_senha}. Vale até {teste_vencimento}."
6. "Deu erro" da Ação ligado a um Atendente.
7. A Mensagem ligada a um bloco Fim.

No n8n, o nó Webhook recebe um JSON com esses quatro campos, e você manda para a planilha. Se ele devolver {"ok": true, "linha": 42}, o fluxo ganha {n8n_ok} e {n8n_linha}, além de {n8n_status}. Para avisar que a venda fechou, o Webhook entra depois da Ação "Cobrar o plano escolhido", mandando {plano_nome} e {fatura_link}.

Erros comuns e cuidados

Pendências que aparecem no cartão enquanto você edita e, ao tentar publicar, no painel do canto do quadro. Todas barram a publicação:

• Informe o endereço que vai receber os dados.
• O endereço precisa começar com https://
• Todo campo com valor precisa de um nome.
• Todo cabeçalho com valor precisa de um nome.
• Ligue a saída "Falhou" ao que o cliente deve receber se o envio não der certo.

E o aviso, que não barra a publicação: A saída "Enviou" está solta: a conversa encerra em silêncio ali.

Cuidados que o validador não pega, mas o motor cobra:

• Só endereço público. IP de rede local e localhost são recusados na chamada, mesmo com https.
• Token em cabeçalho é texto no fluxo. Use um exclusivo do webhook.
• Redirecionamento é falha. Endereço que responde 301 ou 302 sai por "Falhou". Use o endereço final.
• 10 segundos de espera. Um fluxo do n8n que demora mais cai em "Falhou". Responda logo no começo e faça o trabalho pesado em seguida.
• Variável que não veio aparece crua. Uma Mensagem com {n8n_link} manda esse texto ao cliente se o sistema não devolveu link.
• O Testar não chama o webhook. Confira numa conversa de verdade depois de publicar, como explica Testar e publicar.

Perguntas frequentes

O simulador chama o meu webhook de verdade?

Não. Ao chegar no bloco, o simulador avisa que ele "roda no servidor" e mostra dois botões, "Enviou" e "Falhou". O que você escolher define a saída, e a variável de status recebe 200 ou 500 de mentira.

Posso usar a resposta do webhook numa Condição?

Em parte. Na escolha de variável da Condição, o Webhook entra no grupo "Deste fluxo" como "o status HTTP da resposta do webhook" (por baixo, é a {n8n_status}), e você pode comparar com "igual a" 200. Os outros campos, como {n8n_linha}, não aparecem nessa escolha, mas podem ser escritos em qualquer texto de Mensagem, Botões ou Pergunta.

O cliente percebe quando o Webhook roda?

Não. O bloco é de bastidor: nenhuma mensagem sai para o WhatsApp. O que o cliente recebe é o bloco ligado em "Enviou" ou em "Falhou".

Próximos passos

• Como funciona o chatbot: o quadro, a paleta e as palavras do editor.
• Bloco Ação: criar teste, gerar fatura e buscar dados do cliente.
• Bloco Condição: decidir o caminho com o status devolvido.
• Variáveis: tudo o que você pode mandar nos campos.
• Testar e publicar: simulador, pendências e o botão de colocar no ar.