Receber dados de outro sistema: gatilho “Webhook de outro sistema”

Com o gatilho Webhook de outro sistema, cada automação ganha um endereço próprio. Quando outro sistema (a loja virtual, o formulário do site, a plataforma de cursos, o ERP) chama esse endereço com um POST, a automação roda com os dados que ele mandou: dá para mandar uma mensagem ao cliente, avisar a equipe, criar uma negociação ou chamar outro sistema.

O que é

É a porta de entrada do Codewo para avisos de outros sistemas. Muitas plataformas avisam por webhook quando algo acontece do lado delas: compra aprovada, matrícula feita, formulário enviado, boleto pago. Em vez de alguém copiar esses dados à mão, a plataforma chama o endereço da automação e o fluxo segue sozinho.

	Webhook de outro sistema	API	Webhooks de saída
Quem chama	O outro sistema chama o Codewo	O outro sistema chama o Codewo	O Codewo chama o outro sistema
Para quê	Disparar uma automação com os dados recebidos	Ler e gravar contatos, mensagens, produtos e pedidos	Avisar que algo aconteceu no Codewo
Credencial	O próprio endereço (token no link)	Chave de API	Assinatura com o segredo do endpoint
Onde configura	No gatilho da automação	Configurações → Integrações → API & Chaves	Configurações → Integrações → Webhooks

O gatilho faz parte das Automações: não depende da API nem dos webhooks de saída.

Como funciona

O endereço

Ao escolher o gatilho, o painel mostra a URL do Webhook, no formato https://<endereço em que você acessa o Codewo>/api/workflows/webhook/<token>. O token é um código longo e aleatório, criado na hora.

Só a automação dona do endereço roda. Cada automação tem o seu, e um endereço nunca dispara outra automação.
Só funciona com a automação publicada. Em rascunho, pausada ou arquivada, o endereço responde 404 e nada roda.
Aceita apenas POST, de preferência com o corpo em JSON e o cabeçalho Content-Type: application/json.

Como o contato é encontrado

O gatilho não cria contato. Ele procura um contato que já existe na empresa, olhando o primeiro nível do corpo:

Se vier email (ou contact_email), procura o contato com esse e-mail.
Se não vier e-mail, procura pelo phone (ou contact_phone).

A busca é exata. O telefone precisa estar escrito igual ao do cadastro, dígito por dígito. Quando o e-mail vem no corpo, o telefone não é usado na busca, mesmo que o e-mail não encontre ninguém.

Sem contato encontrado, a automação roda do mesmo jeito, mas sem contato: os passos que falam com o contato ou mexem nele não têm com quem agir e aparecem com erro nos resultados. Passos como Avisar pessoas da equipe e Chamar um sistema externo funcionam normalmente.

Os dados nos passos

{{webhook}} é o corpo inteiro recebido, em JSON.
{{webhook.campo}} lê um campo do primeiro nível. Com o corpo {"valor": 297}, {{webhook.valor}} vira 297.
Na aba Mapeamento, você transforma um caminho do corpo numa variável com nome próprio. Em Caminho JSON, escreva o caminho com pontos (curso.nome); em Nome da variável, o nome que vai usar nos passos (curso). A variável fica disponível como {{curso}}. Ao digitar o caminho, a tela preenche o nome da variável sozinha, e nem sempre com o nome certo: confira o que ficou em Nome da variável antes de usar.

A resposta que o outro sistema recebe

Resposta	Significa
`200` com `{"success": true}`	O endereço foi reconhecido. Não garante que a automação rodou
`404`	Endereço desconhecido, token trocado ou automação que não está publicada
`429`	Mais de 60 chamadas por minuto vindas do mesmo endereço IP

A resposta de sucesso não espera a automação rodar. Ela pode não rodar se a assinatura da empresa estiver suspensa ou se uma regra da própria automação barrar. Para saber o que aconteceu, confira os resultados da automação.

Passo a passo

Exemplo: uma escola de cursos livres quer que, a cada matrícula feita na plataforma de cursos, o aluno já cadastrado receba uma mensagem de boas-vindas e a secretaria seja avisada.

Em Automações, clique em Nova automação e escolha Do zero.
Em Como sua automação começa?, escolha Webhook de outro sistema.
Na aba Webhook, clique no botão de copiar ao lado da URL do Webhook.
Na aba Mapeamento, clique em Adicionar, escreva curso.nome em Caminho JSON e deixe curso em Nome da variável. Adicione também curso.turma com o nome turma.
Adicione o passo Enviar mensagem para o contato: "Olá, {{contact.first_name}}! Sua matrícula em {{curso}} (turma {{turma}}) está confirmada." A mensagem vai para a conversa mais recente do aluno. Se ela for pelo WhatsApp oficial e o aluno não escreveu nas últimas 24 horas, use um modelo aprovado no passo.
Adicione o passo Avisar pessoas da equipe para a secretaria: "Nova matrícula: {{webhook.email}} em {{curso}}."
Clique em Publicar.
Na plataforma de cursos, cadastre a URL copiada como destino do aviso de matrícula, pelo método POST, em JSON. Confira se o e-mail do aluno vai no primeiro nível do corpo, com o nome email.

O corpo que a plataforma deve mandar fica assim:

{
  "email": "ana.souza@exemplo.com.br",
  "curso": { "nome": "Planilhas para iniciantes", "turma": "Outubro" },
  "valor": 297
}

Testar

Com a automação publicada e um contato de teste cadastrado com o mesmo e-mail, mande um aviso de verdade. A própria plataforma costuma ter um botão de teste. Se não tiver, quem cuida de sistemas pode usar um comando como este, trocando o endereço pela URL copiada:

curl -X POST "COLE-AQUI-A-URL-DO-WEBHOOK" \
  -H "Content-Type: application/json" \
  -d '{"email": "ana.souza@exemplo.com.br", "curso": {"nome": "Planilhas para iniciantes", "turma": "Outubro"}}'

Depois, abra a automação e use o modo Resultados para ver por onde a execução passou e se algum passo falhou.

Pegadinhas comuns

O endereço é a única senha. Não há assinatura: quem tiver o link dispara a automação. Não coloque o link em código que roda no navegador, como um formulário HTML que envia direto para ele (qualquer visitante vê o endereço no código da página). Prefira que o servidor do formulário faça a chamada.
Vazou? Regenere. O botão Regenerar token troca o endereço e o antigo para de funcionar. Numa automação que já está no ar, a troca vai para o rascunho e só vale depois de Publicar alterações. Até lá, o endereço antigo continua funcionando. Depois, atualize o endereço no outro sistema.
Duplicar a automação copia o endereço. A cópia nasce com o mesmo token da original. Clique em Regenerar token na cópia antes de publicar, senão as duas disputam o mesmo endereço e só uma delas roda.
Contato novo não é cadastrado. Se o aluno ainda não existe no Codewo, a automação não tem com quem falar. Para cadastrar contatos vindos de outro sistema, use a API (veja Chaves de API).
Campos aninhados não acham o contato. Se a plataforma manda {"comprador": {"email": "..."}}, o e-mail está no segundo nível e a busca não o vê. Ajuste o envio na plataforma para trazer email ou phone no primeiro nível.
Telefone precisa bater dígito por dígito. Com ou sem o 55 do país, com ou sem o nono dígito, com ou sem traço: cada diferença faz a busca falhar. Sempre que a plataforma tiver o e-mail, prefira mandar o e-mail.
Sem o cabeçalho de JSON, os dados não são lidos. Corpo em JSON enviado como texto simples chega vazio. Confira se a plataforma manda Content-Type: application/json.
Automação pausada responde 404. Se a plataforma não reenvia os avisos que deram erro, o que chegou durante a pausa se perde.
O construtor marca com um aviso os passos que falam com o contato, dizendo que o gatilho não fornece contato ou conversa, porque este gatilho não garante um contato. O aviso não impede publicar, e o passo funciona quando o contato é encontrado.
Até 60 chamadas por minuto do mesmo endereço IP, somando todos os endereços de automação que ele chama. A chamada recusada não roda a automação. Numa importação em massa, espace os envios.

Boas práticas

Um endereço por sistema de origem. Uma automação para a loja, outra para o formulário. Assim, regenerar o endereço de um não derruba o outro.
Guarde o endereço como uma senha, no cofre de senhas da equipe, e não em planilha compartilhada.
Mande o e-mail sempre que possível. É a forma mais segura de achar o contato.
Teste com um contato real cadastrado antes de ligar o aviso na plataforma para todo mundo.
Use o Mapeamento para campos aninhados. {{curso}} num texto é mais fácil de ler e de manter do que um caminho longo.

Veja também

Nova automação
Automações: gatilhos, passos e caminhos
Testar e acompanhar uma automação
Começando com Webhooks: o caminho inverso, com o Codewo avisando o seu sistema.
Chaves de API: criar, usar e revogar