Como usar n8n com Google Cloud Pub/Sub para ingestão de eventos: guia completo

Aprenda a integrar n8n com Google Cloud Pub/Sub para receber eventos em tempo real e automatizar fluxos sem complicação. Este guia passo a passo cobre desde a configuração do ambiente no Google Cloud até a construção de fluxos robustos no n8n, incluindo tratamento de erros, otimização de performance e boas práticas de segurança.

O que é Google Cloud Pub/Sub e por que usá-lo com n8n?

O Google Cloud Pub/Sub é um serviço de mensageria assíncrona que desacopla produtores e consumidores de eventos, ideal para sistemas que precisam escalar sem bloqueios. Diferente de webhooks tradicionais, ele garante entrega de mensagens mesmo em picos de tráfego, retendo eventos até que o consumidor esteja disponível. Use-o para automações como notificações em tempo real, processamento de logs ou disparo de ações após eventos externos.

No n8n, o Pub/Sub substitui APIs REST polling ou webhooks instáveis, pois recebe mensagens via HTTP push assim que chegam ao tópico. Um exemplo prático: uma compra no seu site gera um evento no Pub/Sub, que o n8n processa para enviar um e-mail de confirmação e registrar no Google Sheets — tudo sem código.

Curiosidade técnica: O Pub/Sub usa um modelo de "assinatura" (subscription) que permite múltiplos consumidores lerem o mesmo tópico sem conflitos, algo impossível com webhooks diretos.

Pré-requisitos: configurando o ambiente no Google Cloud

Você precisa de um projeto no Google Cloud com a API Pub/Sub ativada e uma Service Account com permissões mínimas. Siga os passos abaixo para liberar o acesso:

  1. Crie um projeto no Google Cloud: Acesse Google Cloud Console, clique em "Criar Projeto" e nomeie-o (ex: "n8n-pubsub-automacao").
  2. Habilite a API Pub/Sub: No console, vá em "APIs e Serviços" > "Biblioteca", pesquise por "Pub/Sub" e clique em "Habilitar".
  3. Crie uma Service Account: Em "IAM e administração" > "Service Accounts", clique em "Criar conta de serviço". Digite um nome (ex: "n8n-pubsub-reader") e atribua a role "Pub/Sub Subscriber".
  4. Gere e baixe a chave JSON: Na Service Account, vá em "Chaves" > "Adicionar Chave" > "Criar nova chave" (JSON). Salve o arquivo como `n8n-pubsub-key.json` — você usará ele no n8n. Documentação oficial da Service Account

Como configurar o n8n para se conectar ao Pub/Sub

No n8n, você usará o node HTTP Request para se conectar ao Pub/Sub, seja para publicar ou assinar mensagens. Veja como:

  1. Instale o node HTTP Request: No editor do n8n, clique em "+" > "Nodes" e pesquise por "HTTP Request". Arraste-o para o fluxo.
  2. Configure as credenciais: Crie uma nova credencial do tipo "Google OAuth2 API" ou "JSON" (se usar o arquivo da Service Account). Cole o conteúdo do `n8n-pubsub-key.json` no campo de autenticação.
  3. Defina a URL do endpoint: Para subscribe, use: 
    <code>https://pubsub.googleapis.com/v1/projects/{PROJECT_ID}/subscriptions/{SUBSCRIPTION_NAME}:pull</code>

Para <strong>publish</strong>, use:

<code>https://pubsub.googleapis.com/v1/projects/{PROJECT_ID}/topics/{TOPIC_NAME}:publish</code>

Substitua `{PROJECT_ID}`, `{SUBSCRIPTION_NAME}` e `{TOPIC_NAME}` pelos seus valores.
  4. Diferencie publish vs subscribe: - Publish: Envia mensagens para um tópico (ex: um evento de compra). - Subscribe: Recebe mensagens de uma assinatura (ex: processar eventos no n8n).

Exemplo de payload JSON para publish:

{
  "messages": [
    {
      "data": "SGVsbG8gZnJvbSBudDhuIQ==",
      "attributes": {
        "event_type": "compra_realizada",
        "user_id": "12345"
      }
    }
  ]
}

Curiosidade técnica: O Pub/Sub codifica o payload em base64 por padrão. No n8n, use Buffer.from(payload, 'utf8').toString('base64') para converter mensagens antes de publicar.

Criando um tópico e assinatura no Pub/Sub para n8n

No Google Cloud Console, você cria um tópico para enviar mensagens e uma assinatura para recebê-las no n8n. Siga o passo a passo:

  1. Crie um tópico: No console, vá em "Pub/Sub" > "Tópicos" > "Criar tópico". Nomeie-o (ex: `events-n8n`) e clique em "Criar".
  2. Crie uma assinatura: Em "Assinaturas", clique em "Criar assinatura". Configure: - Nome: `n8n-subscription` (ou qualquer nome). - Endpoint: Para push, use a URL do seu n8n (ex: https://seu-n8n.com/webhook/pubsub). Para pull, deixe em branco e use o node HTTP Request no n8n para puxar mensagens. - Retry policy: Defina um intervalo de retentativa (ex: 10 segundos).
  3. Configure push ou pull: - Push: O Pub/Sub envia mensagens diretamente para o endpoint do n8n (ideal para eventos imediatos). - Pull: O n8n busca mensagens periodicamente (útil para automações self-hosted com tráfego esporádico).

Tabela comparativa: Pub/Sub vs Kafka vs RabbitMQ

Critério Google Pub/Sub Apache Kafka RabbitMQ
Modelo Assíncrono, desacoplado Streaming de eventos Fila de mensagens
Escalabilidade Automática (Google Cloud) Manual (clusters) Limitada (depende de nós)
Custo Pay-as-you-go (R$ 0,01 por milhão de mensagens) Open-source (custos de infra) Open-source (gratuito para uso básico)
Complexidade Baixa (gerenciado) Alta (configuração de clusters) Média (depende de plugins)

Curiosidade técnica: O Pub/Sub retém mensagens por até 7 dias por padrão. Se uma assinatura não consumir uma mensagem dentro desse período, ela é descartada automaticamente.

Construindo o fluxo de automação no n8n: recebendo eventos do Pub/Sub

Monte um fluxo no n8n com 3 nós: HTTP Request (Pub/Sub) → Processamento → Ação final. O Pub/Sub envia mensagens via push para o n8n, que processa o payload e dispara ações como e-mails ou gravações no Google Sheets. Exemplo prático: um evento de compra no e-commerce dispara uma notificação por e-mail e registra os dados no Google Sheets.

  1. Node HTTP Request (Pub/Sub Push): Configure a URL da assinatura Pub/Sub no campo "URL" do node. No n8n, use o método POST e cole a URL da assinatura criada. O Pub/Sub enviará mensagens automaticamente para esse endpoint.
  2. Node Function para decodificar payload: Adicione um node "Function" após o HTTP Request. Use o código abaixo para decodificar o payload base64 e extrair os dados: 
    const payload = items[0].json.message.data;
const decoded = Buffer.from(payload, 'base64').toString('utf8');
return [{ json: { ...JSON.parse(decoded), original_payload: items[0].json } }];
  3. Node de ação final (ex: Send Email): Configure o node de e-mail com os dados decodificados. Exemplo de payload recebido: 
    {
  "message": {
    "data": "eyJldmVudF90eXBlIjogImNvbXBhcmlvX3JlYWxpc2FjaW8iLCAidXNlcl9pZCI6ICIxMjM0NSJ9",
    "attributes": {
      "order_id": "ORD-67890"
    }
  }
}
    Resultado: o n8n envia um e-mail com os detalhes da compra e registra no Google Sheets.

Curiosidade técnica: O Pub/Sub envia o payload sempre em base64, mas os atributos (como order_id) chegam como texto puro no header attributes. Use items[0].json.message.attributes no n8n para acessar esses metadados sem decodificação.

Tratando erros e garantindo confiabilidade no processamento

Configure dead-letter topics no Pub/Sub e use retentativas exponenciais no n8n para mensagens que falham. Crie um fluxo paralelo que redireciona mensagens não processadas para uma fila de recuperação. Exemplo: se o Google Sheets estiver indisponível, a mensagem vai para um tópico dead-letter com até 5 retentativas.

  1. Crie um dead-letter topic e subscription: No Google Cloud Console, crie um tópico dead-letter-events e uma assinatura dlq-subscription com retenção de 10 dias.
  2. Configure retentativas no n8n: No node HTTP Request, ative a opção "Retry on Fail" e defina:
    • Tentativas: 5
    • Intervalo inicial: 1 segundo
    • Fator exponencial: 2
    • Timeout: 30 segundos
  3. Fluxo de erro com Switch node: Adicione um node "Switch" após o processamento principal. Se o status for error, redirecione a mensagem para o node HTTP Request que publica no dead-letter-topic. Exemplo de payload de erro: 
    { "error": "Google Sheets API quota exceeded", "message_id": "12345" }

Curiosidade técnica: O Pub/Sub conta retentativas como tentativas de pull/push. Se uma mensagem falhar 5 vezes, ela é automaticamente enviada para o dead-letter topic — a menos que você configure a política de retentativa no nível da assinatura.

Otimizando performance: loteamento e paralelismo no n8n

Use o node SplitInBatches para processar mensagens em lotes e aproveite o paralelismo do Pub/Sub com múltiplas assinaturas. Configure o n8n para consumir até 100 mensagens por pull e processe-as em paralelo com threads. Exemplo: 1.000 mensagens chegam em 1 segundo — o n8n processa 100 de cada vez em 10 segundos.

  1. Configure Pull com loteamento: No node HTTP Request para Pub/Sub Pull, adicione o parâmetro maxMessages na URL: 
    https://pubsub.googleapis.com/v1/projects/{PROJECT_ID}/subscriptions/{SUBSCRIPTION_NAME}:pull?maxMessages=100
  2. Adicione o node SplitInBatches: Configure o node para dividir as mensagens em lotes de 10. Isso reduz o número de requests para APIs externas (como Google Sheets).
  3. Ative paralelismo no n8n: Em "Settings" > "Execution", defina:
    • Concurrency: 10 (threads paralelas)
    • Batch Size: 100 (mensagens por execução)

Boas práticas para performance:

  • Use Pull em vez de Push se precisar de controle sobre lotes.
  • Configure ackDeadlineSeconds na assinatura para 30 segundos (padrão é 10). Isso dá mais tempo para o n8n processar mensagens grandes.
  • Evite processar mensagens individualmente no n8n — use batch para reduzir custos de APIs externas.
  • Monitore o backlog no Pub/Sub Console para ajustar o tamanho dos lotes.

Curiosidade técnica: O Pub/Sub Pull permite que você ajuste o maxMessages dinamicamente via código. No n8n, use uma expressão como {{ $json.maxMessages || 100 }} na URL para priorizar lotes em horários de pico.

Segurança: autenticação, IAM e boas práticas no Pub/Sub

Restrinja acessos com IAM, use Service Accounts específicas por função e rotacione chaves a cada 90 dias. Nunca use a chave de uma conta "Owner" — dê apenas as permissões mínimas necessárias (ex: roles/pubsub.subscriber para ler mensagens). A criptografia de mensagens deve ser feita antes de publicar, já que o Pub/Sub não criptografa payloads por padrão.

  1. Defina permissões mínimas no IAM: Para uma Service Account que só precisa ler mensagens, atribua a role Pub/Sub Subscriber. Para publicar, use Pub/Sub Publisher. Evite roles como Editor ou Owner.
  2. Rotacione a chave JSON da Service Account: No Google Cloud Console, vá em "IAM e administração" > "Service Accounts" > selecione a conta > "Chaves" > "Rotacionar". Baixe a nova chave e atualize no n8n imediatamente.
  3. Criptografe mensagens antes de publicar: No n8n, use o node "Cryptography" para encriptar o payload antes de enviar ao Pub/Sub. Exemplo com AES-256: 
    const crypto = require('crypto');
const algorithm = 'aes-256-cbc';
const key = crypto.randomBytes(32);
const iv = crypto.randomBytes(16);
const cipher = crypto.createCipheriv(algorithm, key, iv);
let encrypted = cipher.update(JSON.stringify(payload), 'utf8', 'hex');
encrypted += cipher.final('hex');
return [{ json: { encrypted_data: encrypted, iv: iv.toString('hex'), key: key.toString('hex') } }];
  4. Restrinja acesso por IP (opcional): No Google Cloud, configure uma política de firewall para permitir requests apenas do IP do seu n8n. Vá em "VPC Network" > "Firewall" > "Criar regra de firewall" e defina a origem como o IP do servidor.

Aviso crítico: Nunca exponha a chave JSON da Service Account em logs, variáveis de ambiente ou código público. Use o n8n com n8n Cloud ou self-hosted com segurança de rede reforçada.

Curiosidade técnica: O Pub/Sub valida tokens JWT no cabeçalho Authorization para autenticação. Se você usar o node HTTP Request no n8n com a opção "Google OAuth2 API", ele gera automaticamente o token com escopo https://www.googleapis.com/auth/pubsub.

Perguntas frequentes sobre Como usar n8n com Google Cloud Pub/Sub para ingestão de eventos

Como criar um projeto no Google Cloud para usar com Pub/Sub?

Acesse o Google Cloud Console, clique em "Criar Projeto", nomeie-o (ex: "n8n-pubsub-automacao") e confirme. Após criar, habilite a API Pub/Sub em "APIs e Serviços" > "Biblioteca".

Preciso pagar para usar o Google Cloud Pub/Sub com n8n?

O Google Cloud Pub/Sub tem um plano gratuito com 10GB de mensagens por mês. Acima disso, custa R$ 0,01 por milhão de mensagens. Verifique a tabela de preços na documentação oficial para detalhes.

Qual é a diferença entre tópico e assinatura no Pub/Sub?

O tópico é o canal onde as mensagens são publicadas, enquanto a assinatura define quem recebe essas mensagens. Uma assinatura pode ser configurada para push (envio automático) ou pull (busca manual).

Como testar se o Pub/Sub está enviando mensagens corretamente?

Use a ferramenta "Test" no Google Cloud Console ou publique uma mensagem manualmente via API. Verifique se o n8n recebe a mensagem no endpoint configurado ou consulte os logs da assinatura.

Posso usar o Pub/Sub com n8n self-hosted?

Sim, o Pub/Sub funciona com n8n self-hosted. Configure a assinatura para pull e use o node HTTP Request no n8n para buscar mensagens periodicamente.

Como lidar com erros de autenticação no n8n com Pub/Sub?

Verifique se a Service Account tem as permissões corretas (Pub/Sub Subscriber/Publisher) e se a chave JSON está válida. No n8n, teste a conexão com o node HTTP Request antes de prosseguir.

Qual é a melhor forma de processar mensagens em lote no n8n?

Use o node SplitInBatches para dividir mensagens em lotes menores e configure o node HTTP Request com o parâmetro maxMessages na URL (ex: ?maxMessages=100). Isso reduz o número de requests para APIs externas.

Como monitorar o consumo de mensagens no Pub/Sub?

Acesse o Google Cloud Console > Pub/Sub > Assinaturas e verifique o gráfico de backlog ou o número de mensagens não ack. Configure alertas para backlogs altos ou erros de processamento.

Do Pub/Sub ao n8n: transforme eventos em automações poderosas

Integrar n8n com Google Cloud Pub/Sub é a combinação perfeita para quem busca automações em tempo real sem complicações. Com este guia, você aprendeu a configurar ambientes, criar fluxos de trabalho escaláveis e garantir confiabilidade — tudo sem escrever código complexo. Agora, é hora de colocar em prática: publique eventos, processe-os no n8n e automatize ações como notificações, registros ou disparos de APIs.

  • Pub/Sub como backbone de eventos assíncronos;
  • n8n como orquestrador de automações sem código;
  • Segurança com IAM e Service Accounts;
  • Performance com loteamento e paralelismo;
  • Confiança com dead-letter topics e retentativas.

Pronto para transformar seus eventos em automações inteligentes? Explore mais tutoriais na categoria Automação sem Código e descubra como o n8n pode simplificar ainda mais seus fluxos!

Quer mais sobre o assunto? Veja todos os artigos de Ferramentas de IA ou a lista completa de artigos.