Você quer receber um evento via API (Webhook), enviar uma mensagem no WhatsApp via Notifish e registrar o resultado (sucesso/erro) em log.

Esse fluxo é útil para:

• alertas operacionais
• notificações de deploy
• falhas de integração
• notificações de sistema para grupos

Pré-requisitos

1. n8n rodando e acessível
2. endpoint do Notifish (o seu padrão):
   POST https://meu-dominio.notifish.com/api/v2/{INSTANCE_UUID}/whatsapp/message/groups
   com header Authorization: Bearer ...
3. um lugar para log
   Vou te dar 2 opções:

• A) log em arquivo via HTTP (endpoint seu) — mais profissional
• B) log no próprio n8n (Execution data) + uma planilha/banco (se preferir)

Aqui vou usar a opção A (mais “produção”).

Parte 1 — Contrato da API (Webhook)

Você vai expor um endpoint no n8n, por exemplo:

POST https://SEU_N8N/webhook/notify

Payload recomendado (simples e suficiente):

{
  "title": "API 5xx alto",
  "message": "Erros 5xx acima do normal em /api/orders",
  "url": "https://seu-dashboard",
  "identifier": "prod:api:5xx",
  "delayMessage": 0
}

Repare que já mandamos identifier. Isso permite deduplicar e evitar spam.

Parte 2 — Dedupe (anti-spam) usando Redis (opcional, mas recomendado)

Se você tiver Redis (muito comum), dá para usar um passo “check” antes do envio.

• chave: dedupe:{identifier}
• TTL: 300s (5 minutos) por exemplo
  Se existir, você não envia.

Se você não tiver Redis, dá para deduplicar com “Data Store” do n8n ou com um endpoint seu.

Vou te passar o fluxo com Data Store do n8n (não depende de infra extra).

Parte 3 — Enviar WhatsApp via Notifish

O Notifish recebe:

{
  "message": "...",
  "identifier": "...",
  "link": true,
  "typing": "composing",
  "delayMessage": 1200
}

A gente vai montar isso no n8n.

Parte 4 — Registrar Log

Depois do envio (sucesso ou falha), registramos em um endpoint de log. Exemplo:

POST https://seu-sistema.com/api/logs/notifish

Log recomendado:

{
  "identifier": "prod:api:5xx",
  "status": "success",
  "http_status": 200,
  "provider": "notifish",
  "payload": { ... },
  "response": { ... },
  "created_at": "2026-01-22T00:00:00-03:00"
}

NODES DO WORKFLOW (passo a passo)

1) Webhook (Trigger)

• Method: POST
• Path: notify
• Response: JSON (200)

2) Function (Normalize)

Cria um formato consistente e monta a mensagem final do WhatsApp:

• título + mensagem + url
• garante identifier
• define delayMessage

3) Data Store (Get)

Busca identifier na datastore (dedupe).

4) IF (Já enviou?)

Se já existe registro recente, responde 200 “ignored” e não envia.

5) HTTP Request (Notifish)

POST no endpoint do Notifish com Bearer Token.

6) Data Store (Set)

Salva identifier com TTL (ex.: 300s) para dedupe.

7) HTTP Request (Log Success)

Envia log para seu endpoint.

8) Error Trigger / Catch (Log Error)

Se Notifish falhar, manda log com status error.

JSON do workflow para importar no n8n

Abaixo um workflow base. Você só precisa trocar:

• NOTIFISH_INSTANCE_UUID
• NOTIFISH_TOKEN
• LOG_ENDPOINT_URL

Import: n8n → Workflows → Import from file/clipboard

{
  "name": "API → Notifish WhatsApp → Log (com dedupe)",
  "nodes": [
    {
      "parameters": {
        "path": "notify",
        "httpMethod": "POST",
        "responseMode": "lastNode",
        "options": {}
      },
      "name": "Webhook",
      "type": "n8n-nodes-base.webhook",
      "typeVersion": 2,
      "position": [260, 300]
    },
    {
      "parameters": {
        "functionCode": "const body = $json;\n\nconst title = body.title || 'Notificação';\nconst msg = body.message || '';\nconst url = body.url || '';\n\nconst identifier = body.identifier || `generic:${Date.now()}`;\nconst delayMessage = body.delayMessage ?? 0;\n\nconst whatsappMessage = `*${title}*\\n\\n${msg}${url ? `\\n\\n${url}` : ''}`;\n\nreturn [{\n  identifier,\n  delayMessage,\n  notifishPayload: {\n    message: whatsappMessage,\n    identifier,\n    link: true,\n    typing: 'composing',\n    delayMessage\n  },\n  original: body\n}];"
      },
      "name": "Normalize",
      "type": "n8n-nodes-base.function",
      "typeVersion": 2,
      "position": [520, 300]
    },
    {
      "parameters": {
        "operation": "get",
        "key": "={{$json.identifier}}"
      },
      "name": "Dedupe Get",
      "type": "n8n-nodes-base.dataStore",
      "typeVersion": 1,
      "position": [760, 300]
    },
    {
      "parameters": {
        "conditions": {
          "boolean": [
            {
              "value1": "={{$json.value !== undefined && $json.value !== null}}",
              "value2": true
            }
          ]
        }
      },
      "name": "Já enviou?",
      "type": "n8n-nodes-base.if",
      "typeVersion": 2,
      "position": [980, 300]
    },
    {
      "parameters": {
        "respondWith": "json",
        "responseBody": "={\"status\":\"ignored\",\"reason\":\"dedupe\",\"identifier\":\"{{$json.identifier}}\"}",
        "options": {}
      },
      "name": "Return Ignored",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1,
      "position": [1210, 200]
    },
    {
      "parameters": {
        "url": "https://meu-dominio.notifish.com/api/v2/NOTIFISH_INSTANCE_UUID/whatsapp/message/groups",
        "method": "POST",
        "authentication": "none",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Authorization",
              "value": "Bearer NOTIFISH_TOKEN"
            },
            {
              "name": "Content-Type",
              "value": "application/json"
            },
            {
              "name": "Accept",
              "value": "application/json"
            }
          ]
        },
        "sendBody": true,
        "contentType": "json",
        "jsonBody": "={{$json.notifishPayload}}",
        "options": {
          "timeout": 8000
        }
      },
      "name": "Send Notifish",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4,
      "position": [1210, 380]
    },
    {
      "parameters": {
        "operation": "set",
        "key": "={{$json.identifier}}",
        "value": "={{JSON.stringify({sentAt: new Date().toISOString()})}}"
      },
      "name": "Dedupe Set",
      "type": "n8n-nodes-base.dataStore",
      "typeVersion": 1,
      "position": [1450, 380]
    },
    {
      "parameters": {
        "url": "LOG_ENDPOINT_URL",
        "method": "POST",
        "sendHeaders": true,
        "headerParameters": {
          "parameters": [
            {
              "name": "Content-Type",
              "value": "application/json"
            }
          ]
        },
        "sendBody": true,
        "contentType": "json",
        "jsonBody": "={{ {\n  identifier: $json.identifier,\n  status: 'success',\n  provider: 'notifish',\n  response: $json,\n  created_at: new Date().toISOString()\n} }}"
      },
      "name": "Log Success",
      "type": "n8n-nodes-base.httpRequest",
      "typeVersion": 4,
      "position": [1690, 380]
    },
    {
      "parameters": {
        "respondWith": "json",
        "responseBody": "={\"status\":\"sent\",\"identifier\":\"{{$json.identifier}}\"}",
        "options": {}
      },
      "name": "Return OK",
      "type": "n8n-nodes-base.respondToWebhook",
      "typeVersion": 1,
      "position": [1910, 380]
    }
  ],
  "connections": {
    "Webhook": {
      "main": [
        [
          {
            "node": "Normalize",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Normalize": {
      "main": [
        [
          {
            "node": "Dedupe Get",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Dedupe Get": {
      "main": [
        [
          {
            "node": "Já enviou?",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Já enviou?": {
      "main": [
        [
          {
            "node": "Return Ignored",
            "type": "main",
            "index": 0
          }
        ],
        [
          {
            "node": "Send Notifish",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Send Notifish": {
      "main": [
        [
          {
            "node": "Dedupe Set",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Dedupe Set": {
      "main": [
        [
          {
            "node": "Log Success",
            "type": "main",
            "index": 0
          }
        ]
      ]
    },
    "Log Success": {
      "main": [
        [
          {
            "node": "Return OK",
            "type": "main",
            "index": 0
          }
        ]
      ]
    }
  },
  "active": false
}

Observações importantes (produção)

1) Dedupe com Data Store não tem TTL nativo

Ele salva “para sempre” se você não limpar. Em produção, o ideal é:

• usar Redis para TTL real, ou
• incluir timestamp e limpar por job diário

Se você quiser, eu te mando a versão com Redis (TTL real).

2) Log endpoint

Se você não tiver endpoint pronto, você pode logar em:

ou até em um arquivo via API sua

PostgreSQL/MySQL via node de banco

Google Sheets (rápido)

The post Fluxo n8n: API, WhatsApp, Log (com dedupe e tratamento de erro) appeared first on Leonardo Nascimento | Engenheiro de Software.

É nesse contexto que ferramentas como o n8n ganham espaço.

O que é o n8n

O n8n é uma ferramenta de automação baseada em workflows, onde cada fluxo representa uma sequência de ações encadeadas. Essas ações podem envolver chamadas HTTP, processamento de dados, decisões condicionais, integração com serviços externos ou execução de lógica personalizada.

Diferente de scripts isolados ou cron jobs espalhados, o n8n centraliza esse tipo de automação em um único lugar, com visibilidade e controle.

Como o n8n funciona na prática

O funcionamento do n8n se baseia em três conceitos principais:

1) Nodes (nós)

Cada node representa uma ação específica: receber um webhook, chamar uma API, transformar dados, enviar uma mensagem, salvar em banco, entre outros.

2) Workflows

Um workflow é o encadeamento desses nodes. Ele define:

• onde o fluxo começa
• quais decisões são tomadas
• quais ações acontecem em sequência

3) Execuções

Toda vez que um workflow roda, o n8n registra a execução. Isso permite:

• ver entradas e saídas
• identificar erros
• reprocessar execuções

Essa rastreabilidade é um dos pontos fortes da ferramenta.

Onde o n8n costuma ser usado

Na prática, o n8n aparece com frequência em cenários como:

• integração entre sistemas que não se conversam nativamente
• automação de processos manuais repetitivos
• consumo e envio de webhooks
• sincronização de dados entre APIs
• orquestração de tarefas assíncronas

Ele não substitui código em todos os casos, mas reduz bastante a necessidade de escrever lógica repetitiva.

n8n não é “low-code mágico”

Um erro comum é achar que o n8n elimina a necessidade de conhecimento técnico. Na realidade, ele expõe a complexidade de forma visual, mas não a remove.

Para usar bem o n8n, é importante entender:

• HTTP
• APIs REST
• autenticação (tokens, headers, OAuth)
• formatos de dados (JSON)
• tratamento de erros

Sem isso, o fluxo até pode funcionar, mas fica frágil.

A diferença entre automação e orquestração

Automação simples executa tarefas. Orquestração coordena sistemas.

O n8n se destaca quando usado como orquestrador:

• recebe eventos
• decide o que fazer
• chama serviços na ordem correta
• lida com falhas e exceções

Quando bem aplicado, ele vira um ponto central de integração, não apenas um “gatilho”.

Quando faz sentido usar n8n

O n8n costuma ser uma boa escolha quando:

• há muitas integrações externas
• a lógica muda com frequência
• manter código para cada integração ficou caro
• é importante visualizar e auditar fluxos

Ele também é útil para prototipação, desde que exista cuidado para não deixar soluções provisórias virarem definitivas sem revisão.

Quando não faz sentido

Nem tudo precisa de n8n. Em alguns casos, ele adiciona mais uma camada desnecessária.

Exemplos:

• lógica extremamente simples e estável
• processamento pesado ou de alta performance
• fluxos críticos que exigem controle fino de memória ou tempo

Nesses cenários, código direto costuma ser mais adequado.

n8n em produção: pontos de atenção

Rodar n8n em produção exige alguns cuidados:

• persistência de dados (banco configurado corretamente)
• controle de acesso
• versionamento de workflows
• monitoramento de falhas
• cuidado com loops e execuções em massa

Sem isso, a automação vira fonte de problemas, não de solução.

O papel do n8n na arquitetura moderna

O n8n não é o “coração” do sistema, mas funciona bem como camada de integração. Ele conecta serviços, traduz formatos e orquestra eventos, enquanto a regra de negócio principal permanece no backend.

Essa separação ajuda a manter o sistema mais flexível e adaptável a mudanças.

O n8n é uma ferramenta poderosa quando usada com consciência. Ele não substitui engenharia de software, mas resolve muito bem um problema específico: orquestrar integrações e automações de forma clara e controlada.

Quando entra como solução pensada, reduz complexidade. Quando entra como atalho, costuma cobrar seu preço depois.

The post N8N: o que é, como funciona e quando faz sentido usar appeared first on Leonardo Nascimento | Engenheiro de Software.

Essa mudança não aconteceu por moda, mas por necessidade.

O problema de depender apenas de dashboards

Sistemas modernos produzem dados o tempo todo: logs, eventos, erros, métricas, status de filas, integrações externas. Em teoria, tudo isso deveria ser acompanhado por dashboards bem configurados.

Na prática, dashboards só funcionam quando alguém está olhando para eles. Em incidentes reais, o que costuma acontecer é diferente: o problema aparece primeiro no efeito, não na métrica. Quando alguém percebe, o impacto já aconteceu.

É nesse ponto que canais ativos, como o WhatsApp, começam a fazer sentido.

Alertar não é o mesmo que informar

Um erro comum ao levar dados para o WhatsApp é tentar transformar o canal em espelho do sistema: enviar tudo, o tempo todo. O resultado costuma ser o oposto do esperado — excesso de mensagens, ruído e alertas ignorados.

O valor real está em selecionar o que importa, formatar bem a mensagem e entregar no momento certo. Não é sobre volume, é sobre contexto.

A importância de mensagens legíveis

Alertas técnicos mal formatados são tão inúteis quanto a ausência deles. Mensagens longas demais, payloads em JSON ou textos sem hierarquia não ajudam na tomada de decisão.

Em ambientes maduros, o WhatsApp recebe mensagens curtas, diretas e com contexto suficiente para entender:

• o que aconteceu
• onde aconteceu
• se exige ação imediata

Sem isso, o canal perde credibilidade rapidamente.

Quando a simplicidade vira vantagem

Algumas soluções optam por formatos extremamente estruturados, cheios de campos e metadados. Isso funciona bem para sistemas internos, mas não necessariamente para canais humanos.

Ferramentas como o Notifish seguem uma abordagem mais simples: recebem uma mensagem já pronta para leitura, com um identificador básico e controle de entrega. Isso desloca a inteligência para quem envia, não para quem recebe.

Na prática, isso facilita integração com sistemas existentes sem exigir grandes adaptações.

Um padrão que aparece em operações reais

Em operações com volume significativo, o WhatsApp costuma ser usado para:

• alertas críticos de produção
• falhas de integração externa
• eventos que exigem ação humana
• confirmações de processos assíncronos

Ele não substitui logs, métricas ou ferramentas de observabilidade. Ele complementa, cobrindo o espaço entre o evento técnico e a reação humana.

O risco de transformar alerta em ruído

Sempre que um novo canal é adicionado, surge o risco de exagero. Alertar tudo é quase tão ruim quanto não alertar nada.

Operações estáveis costumam ter regras claras:

• poucos tipos de alerta
• mensagens bem definidas
• identificação para evitar duplicidade
• silêncio como padrão

Quando o WhatsApp segue essa lógica, ele se mantém útil. Quando vira canal genérico, é rapidamente ignorado.

Integração como parte da arquitetura, não como atalho

Outro ponto importante é tratar a integração com WhatsApp como parte da arquitetura do sistema, e não como um remendo. Isso significa:

• decidir onde o alerta nasce
• quem é responsável por enviá-lo
• quando ele deve ser disparado
• e quando não deve

Sem esse cuidado, qualquer ferramenta vira apenas mais uma dependência.

Conclusão

O WhatsApp deixou de ser apenas um meio de comunicação informal e passou a ocupar um espaço relevante em operações técnicas. Quando usado com critério, ele encurta o tempo entre o problema e a reação.

Ferramentas que respeitam essa lógica — simples na entrada, claras na saída — tendem a se encaixar melhor em sistemas reais. Não por prometerem mais, mas por atrapalharem menos.

The post Quando o WhatsApp vira canal operacional (e não só meio de envio) appeared first on Leonardo Nascimento | Engenheiro de Software.

1. criar a instância
2. conectar o WhatsApp (QR Code)
3. enviar a mensagem

Se pular qualquer um deles, não funciona.

1️⃣ Confirmar dados básicos da instalação

Você precisa ter em mãos:

• Server URL
  Exemplo: https://api.seudominio.com
• API Key global (gerada pelo Orion na instalação)

Esses dois dados são usados em todas as chamadas.

2️⃣ Criar a instância (obrigatório)

Na Evolution API v2, não existe envio sem instância.

Endpoint

POST /instance/create

Exemplo com curl

curl -X POST https://api.seudominio.com/instance/create \
  -H "apikey: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "instanceName": "primeira-instancia"
  }'

Resposta esperada

Algo semelhante a:

{
  "instance": {
    "instanceName": "primeira-instancia",
    "status": "created"
  }
}

Se deu erro aqui, pare. O resto não vai funcionar.

3️⃣ Conectar o WhatsApp (QR Code)

Depois da instância criada, você precisa conectar o número.

Gerar QR Code

GET /instance/connect/{instanceName}

curl -X GET https://api.seudominio.com/instance/connect/primeira-instancia \
  -H "apikey: SUA_API_KEY_AQUI"

A resposta vem com o QR Code em base64 ou link.

Abra no navegador ou use o manager do Orion:

https://api.seudominio.com/manager

Escaneie com o WhatsApp do celular.

Verificar status da instância

Antes de enviar mensagem, confirme que está conectada.

GET /instance/connectionState/{instanceName}

curl -X GET https://api.seudominio.com/instance/connectionState/primeira-instancia \
  -H "apikey: SUA_API_KEY_AQUI"

Status esperado:

{
  "state": "open"
}

Se não estiver open, não adianta tentar enviar mensagem.

4️⃣ Primeiro disparo de mensagem (texto simples)

Agora sim.

Endpoint v2 para texto

POST /message/sendText/{instanceName}

Exemplo real

curl -X POST https://api.seudominio.com/message/sendText/primeira-instancia \
  -H "apikey: SUA_API_KEY_AQUI" \
  -H "Content-Type: application/json" \
  -d '{
    "number": "559999999999",
    "text": "Olá! Este é meu primeiro disparo pela Evolution API v2."
  }'

⚠️ Formato do número

• Sempre com DDI + DDD + número
• Sem +, sem espaço, sem traço

Exemplo válido:

5591999999999

5️⃣ O que acontece se não enviar?

Os erros mais comuns no primeiro disparo:

❌ Instância não conectada

Resposta típica:

instance not connected

❌ Número inválido

• faltou DDI
• tem +
• tem espaço

❌ API Key errada

Resposta:

Unauthorized

❌ Endpoint errado (v1 ≠ v2)

Na v2:

/message/sendText/{instance}

Na v1 era diferente. Não misture.

6️⃣ Teste rápido pelo Manager (opcional)

Se quiser validar sem curl:

1. Acesse: https://api.seudominio.com/manager
2. Escolha a instância
3. Vá em Send Message
4. Envie um texto simples

Se funciona no manager e não via API, o problema é payload ou headers.

7️⃣ Próximos disparos possíveis (depois do primeiro)

Depois que o texto simples funciona, você pode evoluir para:

• imagem
• vídeo
• áudio
• botão
• lista
• disparos em massa
• integração com Laravel, n8n, Notifish etc.

Mas sempre valide texto primeiro.

Resumo rápido (ordem correta)

1️⃣ criar instância
2️⃣ conectar WhatsApp
3️⃣ confirmar state = open
4️⃣ enviar sendText

Se seguir isso, funciona.

The post Como fazer o primeiro disparo na Evolution API appeared first on Leonardo Nascimento | Engenheiro de Software.