Guia Node-RED no CentOS 9 para webhooks do Mercado Pago

10 min de leitura  ·  Guia técnico

Node-RED no CentOS 9 é uma ferramenta de automação de fluxos baseada em Node.js que recebe e processa notificações HTTP, ideal para tratar webhooks do Mercado Pago sem escrever uma aplicação completa. Para configurá-lo do zero, siga estes passos:

1. Instale o Node.js LTS e o Node-RED via npm no CentOS 9.
2. Crie uma unidade systemd para iniciar o serviço automaticamente.
3. Monte um fluxo com nós http in, http response e function.
4. Publique o endpoint atrás de um proxy reverso Nginx com HTTPS.
5. Cadastre a URL no painel de desenvolvedor do Mercado Pago.
6. Valide a assinatura x-signature antes de processar o evento.

Pré-requisitos para rodar Node-RED no CentOS 9

Antes de iniciar, garanta que o ambiente atenda aos requisitos abaixo. Trabalhar com automação de pagamentos exige um servidor estável e com acesso administrativo completo.

• VPS ou servidor dedicado com CentOS Stream 9 atualizado.
• Acesso root ou usuário com privilégios sudo via SSH.
• Node.js 20 LTS ou superior e npm instalados.
• Conta no Mercado Pago com acesso ao painel de desenvolvedor e às credenciais (access token e chave secreta de webhook).
• Um domínio ou subdomínio apontado para o IP do servidor, com certificado SSL.
• Firewalld ativo para controlar as portas expostas.

Se você ainda não consegue se conectar ao servidor, consulte o guia Acessando servidores VPS Linux da AviraHost antes de prosseguir.

Como instalar o Node-RED no CentOS 9

A instalação da plataforma de fluxos começa pelo runtime Node.js. No CentOS Stream 9, o repositório do AppStream traz versões recentes, mas para automação de webhooks vale usar o módulo Node.js 20.

1. Atualize o sistema e instale as ferramentas de compilação:

sudo dnf update -y
sudo dnf install -y gcc-c++ make git
sudo dnf module install -y nodejs:20/common

Verifique a versão instalada:

node -v
npm -v

v20.x.x
10.x.x

2. Instale o Node-RED globalmente via npm:

sudo npm install -g --unsafe-perm node-red

3. Crie um usuário dedicado e inicie o serviço uma vez para gerar a pasta de configuração:

sudo useradd -m -r -s /usr/sbin/nologin nodered
sudo -u nodered HOME=/home/nodered node-red

Ao rodar este comando, você verá no terminal a linha Server now running at http://127.0.0.1:1880/. Pressione Ctrl+C para encerrar — a pasta /home/nodered/.node-red já estará criada com o arquivo settings.js.

Configurar o serviço node-red com systemd no CentOS

Para que a automação de pagamentos sobreviva a reinicializações, o ideal é registrar o Node-RED como serviço gerenciado pelo systemd. Sem isso, o processo morre ao fechar a sessão SSH.

1. Crie o arquivo de unidade:

sudo nano /etc/systemd/system/nodered.service

Cole o conteúdo abaixo:

[Unit]
Description=Node-RED
After=network.target

[Service]
Type=simple
User=nodered
Environment="NODE_OPTIONS=--max-old-space-size=256"
WorkingDirectory=/home/nodered
ExecStart=/usr/bin/node-red --userDir /home/nodered/.node-red
Restart=on-failure
KillSignal=SIGINT

[Install]
WantedBy=multi-user.target

2. Recarregue, habilite e inicie o serviço:

sudo systemctl daemon-reload
sudo systemctl enable --now nodered

Confirme que está ativo:

sudo systemctl status nodered

● nodered.service - Node-RED
   Active: active (running) since ...

Com enable, o editor de fluxos voltará sozinho após qualquer reboot, garantindo que nenhuma notificação de pagamento seja perdida.

Expor o webhook com Nginx como proxy reverso e HTTPS

Publicar o painel diretamente na porta 1880 é arriscado. A prática recomendada é manter essa porta restrita ao localhost e usar o Nginx para encaminhar apenas o endpoint de notificações via HTTPS na porta 443.

Instale o Nginx e libere as portas no firewalld:

sudo dnf install -y nginx
sudo systemctl enable --now nginx
sudo firewall-cmd --permanent --add-service=http
sudo firewall-cmd --permanent --add-service=https
sudo firewall-cmd --reload

Atenção: não adicione a porta 1880 ao firewall. Ela deve permanecer acessível somente internamente para reduzir a superfície de ataque.

Crie o virtual host em /etc/nginx/conf.d/webhook.conf:

server {
    listen 80;
    server_name webhook.seudominio.com.br;

    location /mp-webhook {
        proxy_pass http://127.0.0.1:1880/mp-webhook;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Teste e recarregue a configuração:

sudo nginx -t
sudo systemctl reload nginx

Para o certificado SSL gratuito, siga o passo a passo do artigo instalação do Certbot adaptando os comandos para o CentOS 9. Um endpoint sem HTTPS é rejeitado por boas práticas de integração de pagamentos.

Criar o fluxo de webhook do Mercado Pago no Node-RED

Agora vem o coração da integração de notificações: o fluxo que recebe o POST, responde rápido e processa o evento. Acesse o editor em http://127.0.0.1:1880 usando um túnel SSH local ou após proteger o painel.

1. Adicione um nó http in configurado com método POST e URL /mp-webhook.
2. Conecte imediatamente um nó http response com código de status 200.
3. Em paralelo, ligue o http in a um nó function para a lógica de validação.

No nó function, extraia os cabeçalhos e o corpo enviados pelo Mercado Pago:

const signature = msg.req.headers["x-signature"];
const requestId = msg.req.headers["x-request-id"];
const dataId = msg.payload.data ? msg.payload.data.id : null;

msg.evento = {
    tipo: msg.payload.type,
    recurso: dataId,
    signature: signature,
    requestId: requestId
};
return msg;

Como o Mercado Pago envia apenas o ID do recurso, use um nó http request seguinte para consultar os detalhes completos do pagamento na API, enviando o seu access token no cabeçalho Authorization: Bearer. Responder o 200 antes de consultar a API evita timeouts e reenvios.

Validar a assinatura x-signature do webhook

A verificação de autenticidade impede que terceiros disparem fluxos falsos. O Mercado Pago monta um HMAC-SHA256 com base no x-request-id, no ID do recurso e no timestamp presente no próprio cabeçalho.

Em um nó function, separe as partes do cabeçalho e calcule o hash:

const crypto = global.get("crypto") || require("crypto");
const partes = msg.evento.signature.split(",");
const ts = partes[0].split("=")[1];
const hash = partes[1].split("=")[1];

const manifest = `id:${msg.evento.recurso};request-id:${msg.evento.requestId};ts:${ts};`;
const segredo = "SUA_CHAVE_SECRETA_DE_WEBHOOK";

const calculado = crypto
    .createHmac("sha256", segredo)
    .update(manifest)
    .digest("hex");

msg.valido = (calculado === hash);
return msg;

Para usar o módulo crypto, habilite-o no settings.js dentro de functionGlobalContext. Se msg.valido for falso, descarte a notificação. Nunca registre a chave secreta em logs.

Problemas comuns e como resolver

Sintoma: o webhook responde, mas o Mercado Pago marca como falha

Causa: a resposta HTTP demora demais ou retorna um código diferente de 200/201.
Solução: garanta que o nó http response esteja conectado diretamente ao http in, antes de qualquer consulta à API. Mova a lógica pesada para depois da resposta, processando em paralelo.

Sintoma: erro 502 Bad Gateway no Nginx ao receber a notificação

Causa: o serviço node-red não está rodando ou o proxy_pass aponta para a porta errada.
Solução: rode sudo systemctl status nodered e verifique se escuta em 127.0.0.1:1880. Cheque também o SELinux com sudo setsebool -P httpd_can_network_connect 1, pois o CentOS 9 bloqueia conexões de saída do Nginx por padrão.

Sintoma: a assinatura nunca confere

Causa: o manifest foi montado com campos na ordem errada ou a chave secreta está incorreta.
Solução: confirme a sequência exata id;request-id;ts; e copie a chave secreta diretamente da configuração de webhooks no painel do Mercado Pago, sem espaços extras.

Perguntas frequentes sobre Node-RED e webhooks do Mercado Pago

Qual porta o Node-RED usa por padrão e como deixá-la acessível?

O Node-RED escuta na porta 1880 por padrão. Em produção, recomenda-se mantê-la fechada no firewall e publicar o serviço através de um proxy reverso Nginx com HTTPS na porta 443, expondo apenas o endpoint de webhook necessário.

Como o Mercado Pago envia notificações de webhook?

O Mercado Pago envia uma requisição HTTP POST para a URL configurada no painel de desenvolvedor sempre que ocorre um evento, como pagamento aprovado. O corpo contém o tipo de evento e o ID do recurso, que você usa para consultar os detalhes via API.

Preciso validar a assinatura dos webhooks do Mercado Pago?

Sim. O Mercado Pago envia o cabeçalho x-signature com um hash HMAC e o cabeçalho x-request-id. Validar esse hash com a sua chave secreta garante que a notificação é legítima e evita que terceiros disparem fluxos falsos no seu servidor.

O Node-RED inicia sozinho após reiniciar o CentOS 9?

Apenas se você criar uma unidade systemd e habilitá-la com systemctl enable. Sem isso, o processo não reinicia automaticamente após reboot ou queda. O serviço node-red oficial já fornece um exemplo de unit que pode ser adaptado.

Posso usar o Node-RED para responder o webhook em menos de 22 segundos?

Sim, e isso é recomendado. O Mercado Pago espera resposta HTTP 200 ou 201 rapidamente; por isso responda imediatamente com o nó http response e processe a lógica pesada em paralelo, evitando reenvios por timeout.

Conclusão

• Instale o Node-RED como serviço systemd para garantir reinício automático e disponibilidade contínua das notificações.
• Exponha apenas o endpoint /mp-webhook via Nginx com HTTPS, mantendo a porta 1880 restrita ao localhost.
• Responda o POST com status 200 imediatamente e valide o x-signature antes de processar qualquer evento de pagamento.

Leia também

• guia: como usar webhooks para automatizar deploys
• Como Configurar Backup Automatizado do MySQL sem Plugin
• n8n no VPS Linux: instale e automatize em 2026

Precisa de ajuda com automação de webhooks no seu servidor?

Um VPS estável com acesso root é a base ideal para rodar Node-RED, Nginx e suas integrações de pagamento com desempenho e controle total.

Conheça os planos de VPS da AviraHost