Mautic com n8n e API
O cadastro feito no checkout ou na agenda precisa chegar ao Mautic sem importação de planilha. A API REST da instância aceita OAuth2 ou Basic Auth para criar e atualizar contatos, o Node Mautic do n8n faz essas chamadas num workflow e os webhooks assinados avisam o n8n quando um formulário é enviado.
Ficha e sumário da página
- Referência técnica
- Mautic 7.2.2
- Revisão
- 13 de novembro de 2026
- Conteúdo
- Documentação oficial consultada
A API REST e as duas formas de autenticar
A API do Mautic responde no caminho /api/ da instância, como https://mautic.seudominio.com.br/api/contacts para os contatos. Você liga a API em Configuração, nas configurações da API. Com a API ligada, o menu de credenciais da API aparece para o administrador. É nesse menu que você cria o Client ID e o Client Secret de cada integração.
O Mautic aceita duas formas de autenticação. O Basic Auth manda o nome de acesso e a senha de um usuário do Mautic em cada requisição. Ele precisa ser ligado à parte, nas mesmas configurações ou com api_enable_basic_auth no config/local.php. O OAuth2 usa um token de acesso com prazo de validade. A documentação recomenda essa forma por segurança.
O OAuth2 do Mautic aceita três fluxos. O authorization_code serve para integrações nas quais cada usuário entra com a própria senha do Mautic. O client_credentials serve para máquina falando com máquina, como um workflow agendado. O refresh_token renova o acesso sem repetir o login. O token sai do endereço /oauth/v2/token, com o tempo de vida em expires_in, como os 3.600 segundos do exemplo oficial. O token de renovação vale 14 dias no padrão, prazo que você altera nas configurações da API. A requisição leva o token no cabeçalho Authorization: Bearer.
O Node Mautic do n8n
No n8n, o Node Mautic chama essa API por você. As operações ficam agrupadas por recurso:
O guia Conecte o Mautic ao n8n pelo Node nativo, da central de n8n da Promovaweb, mostra a credencial com Basic Auth ou OAuth2 e a conferência no destino. A credencial OAuth2 nativa do n8n usa o fluxo authorization_code. O suporte do Mautic a client_credentials não significa que esse fluxo esteja disponível nessa credencial. O n8n também tem o Mautic Trigger, um Node de gatilho próprio para receber eventos do Mautic.
Webhooks: o Mautic avisa o n8n
O webhook do Mautic envia informações dos contatos e da atividade deles para outro sistema. Na criação, você dá um nome, informa a URL que recebe o POST e marca os eventos que disparam o envio. Com o n8n, essa URL é a de um Node Webhook do workflow. O botão de envio de teste manda um exemplo de payload para conferir a ligação.
A documentação lista 14 eventos. Os de contato cobrem a identificação, a atualização, a mudança de pontos, a exclusão e a troca de inscrição num canal. Os de empresa cobrem a criação, a atualização e a exclusão. Os de atividade registram o envio e a abertura de e-mails, o envio de formulários, as visitas às páginas e o envio de mensagens de texto. Cada evento tem uma chave no payload:
mautic.lead_post_save_newContato identificado pela primeira vez.mautic.lead_post_save_updateContato atualizado.mautic.lead_points_changePontos do contato alterados.mautic.form_on_submitFormulário enviado.mautic.email_on_openE-mail aberto.mautic.page_on_hitVisita a uma página rastreada.
O envio acontece de dois jeitos. No modo imediato, o Mautic faz o POST quando o evento acontece. No modo de fila, os eventos esperam o comando mautic:webhooks:process no cron e saem em lote, com vários tipos de evento no mesmo envio, na ordem cronológica ou na inversa.
Formulário enviado
mautic.form_on_submitO contato preenche o formulário no seu site.
Webhook
POST para o n8nO Mautic envia o evento com o cabeçalho Webhook-Signature.
Conferência
HMAC-SHA256O workflow calcula a assinatura com a chave secreta e compara.
Outros sistemas
CRM, planilha, WhatsAppO workflow repassa o cadastro para onde ele faz falta.
Volta ao Mautic
Update a contactO Node Mautic grava o resultado, como uma tag nova.
A assinatura de cada aviso
A URL do webhook precisa ser acessível ao Mautic. Se ela estiver pública, outro sistema também pode mandar um POST para esse endereço. A assinatura permite ao receptor conferir se o corpo recebido corresponde ao cálculo feito com a chave secreta compartilhada. O Mautic envia o cabeçalho Webhook-Signature com o HMAC-SHA256 do corpo bruto da requisição, calculado com essa chave e codificado em base64. A documentação orienta o sistema que recebe a calcular a própria assinatura e ignorar toda requisição com assinatura diferente.
No exemplo do diagrama, você implementa essa conferência no workflow antes de qualquer gravação. O corpo usado no cálculo precisa ser o corpo bruto, como chegou. Converter o conteúdo em JSON e serializá-lo novamente pode alterar os bytes e produzir uma assinatura diferente. A verificação não é automática só porque o workflow recebeu o POST.
A campanha chamando o n8n
O caminho também existe dentro das campanhas. A ação Send a Webhook, no construtor, faz a requisição para a URL que você informa no ponto escolhido do fluxo, como depois de uma abertura registrada. O workflow do n8n pode criar uma oportunidade no CRM ou mandar uma mensagem para o vendedor responsável. Essa ação tem configuração própria de requisição e não deve ser confundida com os webhooks de eventos descritos acima. Ela e as demais ações estão na página Campanhas.
Com a API, os webhooks e o Node Mautic, o Mautic e o n8n dividem o trabalho na sua VPS: o Mautic guarda os contatos, as campanhas e o histórico de envios. O n8n liga esse cadastro ao checkout, ao CRM e aos outros apps que você usa.
Continue na comunidade
Leve ao Discord da Promovaweb o segmento que não atualiza ou a campanha que parou no meio. Com o log do cron na conversa, a comunidade compara o seu caso com instâncias parecidas.
Uma VPS para o seu Mautic
O Mautic mantém o painel, o cron e o worker no ar ao lado do MySQL. A VPS da StayCloud em São Paulo vem com acesso root e disco NVMe para os três papéis e o banco ficarem na mesma máquina.
Link de parceiro da Promovaweb.