Correlation ID não é “ID do cliente” (e nem o ID do pedido)
Muita automação no Brasil começa com um identificador já existente: número do pedido, telefone, e-mail, ID do lead. Isso ajuda, mas não resolve o principal: uma mesma pessoa pode gerar várias execuções, várias tentativas (retry) e vários eventos parecidos.
Correlation ID é diferente: ele identifica a execução lógica daquela jornada. Se o workflow reprocessar, cair em fila, chamar três APIs e voltar, você ainda consegue dizer: “tudo isso aqui foi o mesmo caso”.
Para que serve na prática (os 4 ganhos que mais aparecem)
Onde ele brilha é no dia a dia de operação — especialmente quando você já passou da fase “funciona na minha máquina” e começou a ter volume, time e dependências.
- Debug rápido: você pesquisa 1 valor e encontra todos os logs daquela jornada.
- Auditoria: dá para reconstruir o caminho (quem chamou quem, quando, e com qual payload “resumido”).
- Controle de duplicidade: facilita provar que dois eventos são repetição do mesmo gatilho (mesmo correlation ID) vs. dois casos distintos.
- Atendimento interno: suporte/comercial consegue pedir “me manda o correlation ID” e parar de depender de prints.
Onde colocar o Correlation ID (headers, payload, logs e banco)
Você não precisa escolher um lugar só. O padrão mais resiliente é: header + campo no payload + persistência mínima em algum log/banco.
| Ponto do fluxo | Como passar o Correlation ID | Observação prática |
|---|---|---|
| Webhook de entrada | Gerar e anexar (ex.: header X-Correlation-Id) | Se o cliente já manda um ID, você pode reaproveitar, mas valide formato/colisão. |
| Chamadas HTTP para APIs | Repassar em header (X-Correlation-Id) e/ou query | Nem toda API registra isso, mas você registra do seu lado. |
| Filas (RabbitMQ/SQS/Kafka) | Incluir em atributos/headers da mensagem | Ajuda a rastrear retries, DLQ e reprocessamento. |
| Logs do orquestrador (n8n/Make) | Logar em cada etapa crítica | Evite logar dados sensíveis; logue o ID e um resumo. |
| Banco (tabela de eventos) | Salvar correlation_id + status + timestamps | Cria trilha de auditoria sem depender só do histórico da ferramenta. |
Como gerar: UUID serve, mas o ponto é consistência
O caminho mais comum é gerar um UUID no início do fluxo (no primeiro nó/step) e guardar numa variável. Se você já recebe um identificador do sistema de origem (por exemplo, um event_id confiável), dá para usar como correlation ID — desde que ele seja único por tentativa e não só por entidade.
Se você não tem certeza se o ID recebido é realmente único por evento, prefira criar o seu e guardar também o ID original (ex.: source_event_id). Assim você cruza as duas visões.
Checklist rápido (sem romantizar): o mínimo que funciona
Se você só fizer o básico abaixo, já melhora muito a vida de quem opera a automação:
- Gerar correlation ID no gatilho (ou aceitar o que veio, validando).
- Propagar o mesmo valor em todas as chamadas HTTP e mensagens em fila.
- Logar o correlation ID nas etapas que falham (e no sucesso final).
- Persistir status final (OK/erro) + correlation ID em uma tabela/planilha de eventos.
- Nunca usar correlation ID como segredo (ele não é token de segurança).
Erros comuns que fazem o Correlation ID “não servir pra nada”
Dá para implementar e ainda assim continuar cego. Os tropeços mais comuns são bem previsíveis:
- Gerar um ID novo em cada nó (você perde a linha do tempo do caso).
- Logar o ID só no começo e nunca mais (na hora da falha, cadê?).
- Misturar ID de entidade (cliente/pedido) com ID de execução (correlação).
- Colocar o ID, mas não propagar para filas/retries (justo onde mais precisa).
- Salvar correlation ID junto com dados sensíveis em texto puro (desnecessário e perigoso).
Perguntas frequentes
Correlation ID é a mesma coisa que Idempotency Key?
No n8n e no Make eu consigo usar Correlation ID sem programar?
Posso usar o número do pedido como correlation ID?
Correlation ID ajuda em filas e DLQ (dead-letter queue)?
Termos relacionados
Observabilidade no n8n self-hosted: como montar métricas, logs e alertas (sem adivinhação)
Guia prático para monitorar n8n self-hosted com logs, métricas e alertas. O que medir, como estruturar correlação por execução e como evitar “apagão” quando um fluxo falha.
Ler →
Como monitorar automações (n8n, Make e Zapier): alertas, logs e erros sem virar refém do “falhou e ninguém viu”
Guia prático para monitorar automações em n8n, Make e Zapier: quais alertas criar, como registrar logs, tratar erros, retries e evitar falhas silenciosas.
Ler →
Idempotency-Key: o que é e como usar em automações (sem pedido duplicado)
Entenda Idempotency-Key (chave de idempotência): por que evita duplicidade em pagamentos, pedidos e webhooks, quando usar, como gerar e como implementar em automações como n8n/Make via headers e banco.
Ler →
Circuit breaker em automações (n8n/Make/Zapier): como evitar cascata de erros quando uma API cai
Guia prático para aplicar padrão circuit breaker em automações no n8n, Make ou Zapier: quando abrir/fechar, como detectar falhas, fallback, filas e alertas para não derrubar sua operação.
Ler →