Ir para o conteúdo
Promovaweb

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
  1. A API REST e as duas formas de autenticar
  2. O Node Mautic do n8n
  3. Webhooks: o Mautic avisa o n8n
  4. A assinatura de cada aviso
  5. A campanha chamando o n8n

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:

RecursoOperações do Node MauticUso comum num workflow
ContactCriar, atualizar, apagar, consultar um ou todos, mudar os pontos, enviar e-mail e mexer na lista de não contatar.Gravar o cliente aprovado no checkout com nome, e-mail e tags.
Contact SegmentAdicionar o contato a um segmento ou tirar dele.Colocar o comprador no segmento de clientes na hora.
Campaign ContactAdicionar o contato a uma campanha ou tirar dele.Iniciar a sequência de boas-vindas sem esperar o cron dos segmentos.
Company e Company ContactCriar, atualizar, apagar e consultar empresas. Adicionar ou remover os contatos associados.Registrar a empresa de um lead que veio de um formulário de outro site.
Segment EmailEnviar um e-mail de segmento.Disparar o envio quando outro sistema confirma uma data.

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.

  1. Formulário enviado

    mautic.form_on_submit

    O contato preenche o formulário no seu site.

  2. Webhook

    POST para o n8n

    O Mautic envia o evento com o cabeçalho Webhook-Signature.

  3. Conferência

    HMAC-SHA256

    O workflow calcula a assinatura com a chave secreta e compara.

  4. Outros sistemas

    CRM, planilha, WhatsApp

    O workflow repassa o cadastro para onde ele faz falta.

  5. Volta ao Mautic

    Update a contact

    O Node Mautic grava o resultado, como uma tag nova.

Um formulário do Mautic atualizando outro sistema pelo n8n: o webhook envia o evento assinado, o workflow confere a assinatura e o Node Mautic grava o resultado de volta na ficha. Os nomes vêm da documentação do Mautic 7.2 e do n8n.

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.

Ver a VPS da StayCloud

Link de parceiro da Promovaweb.