Como integrar validação de CPF em HubSpot com workflows customizados

Para validar CPF de leads diretamente no HubSpot, crie um workflow baseado em contatos com uma custom code action em Node.js que chama a API da CPFHub.io e grava os dados retornados — nome, data de nascimento e gênero — nas propriedades customizadas do contato. O processo é automatizado e não requer intervenção manual após a configuração.

Introdução

O HubSpot é uma das plataformas de CRM e automação de marketing mais completas do mercado. Para empresas brasileiras que usam HubSpot, validar o CPF de leads e contatos diretamente nos workflows automatiza processos de qualificação, compliance e prevenção de fraudes. A documentação oficial do HubSpot detalha todas as opções disponíveis para atualizar propriedades de contato via API — incluindo o endpoint PATCH usado no exemplo de webhook deste artigo.

1. Pré-requisitos

• HubSpot com plano Professional ou Enterprise (necessário para custom code em workflows).

• Propriedades customizadas de contato criadas no HubSpot para CPF e dados de validação.

• Uma conta na CPFHub.io com a API key gerada no painel.

2. Crie as propriedades customizadas

No HubSpot, acesse Settings > Properties e crie as seguintes propriedades de contato:

• cpf_numero — Single-line text — CPF do contato.

• cpf_nome_validado — Single-line text — Nome retornado pela validação.

• cpf_genero — Dropdown select — Masculino / Feminino.

• cpf_data_nascimento — Single-line text — Data de nascimento retornada.

• cpf_status — Dropdown select — Pendente / Validado / Erro.

3. Crie o workflow

Em Automation > Workflows, crie um novo workflow baseado em contatos:

• Trigger — "Contact property value is known" para a propriedade cpf_numero. Isso dispara o workflow quando um CPF é preenchido.

• Filtro adicional — cpf_status is "Pendente" ou is unknown (para evitar reprocessamento).

4. Adicione a custom code action

No workflow, adicione uma ação do tipo Custom code. Selecione Node.js 18 como runtime e insira o seguinte código:

const axios = require('axios');

exports.main = async (event, callback) => {
    const cpf = event.inputFields['cpf_numero']?.replace(/\D/g, '');

    if (!cpf || cpf.length !== 11) {
    callback({
    outputFields: {
    cpf_status: 'Erro',
    cpf_nome_validado: '',
    cpf_data_nascimento: '',
    cpf_genero: ''
    }
    });
    return;
    }

    try {
    const response = await axios.get(`https://api.cpfhub.io/cpf/${cpf}`, {
    headers: {
    'x-api-key': process.env.CPFHUB_API_KEY || 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    },
    timeout: 5000
    });

    const dados = response.data;

    if (dados.success) {
    callback({
    outputFields: {
    cpf_status: 'Validado',
    cpf_nome_validado: dados.data.name,
    cpf_data_nascimento: dados.data.birthDate,
    cpf_genero: dados.data.gender === 'M' ? 'Masculino' : 'Feminino'
    }
    });
    } else {
    callback({
    outputFields: {
    cpf_status: 'Erro',
    cpf_nome_validado: '',
    cpf_data_nascimento: '',
    cpf_genero: ''
    }
    });
    }
    } catch (error) {
    callback({
    outputFields: {
    cpf_status: 'Erro',
    cpf_nome_validado: '',
    cpf_data_nascimento: '',
    cpf_genero: ''
    }
    });
    }
};

Configuração dos campos

Na aba Inputs da custom code action, mapeie:

• cpf_numero — propriedade de contato cpf_numero.

Na aba Outputs, defina:

• cpf_status — String
• cpf_nome_validado — String
• cpf_data_nascimento — String
• cpf_genero — String

5. Atualize as propriedades do contato

Após a custom code action, adicione ações de Set contact property para gravar os outputs:

• cpf_status = output cpf_status
• cpf_nome_validado = output cpf_nome_validado
• cpf_data_nascimento = output cpf_data_nascimento
• cpf_genero = output cpf_genero

6. Exemplo de resposta da API

Quando a validação é bem-sucedida, a API da CPFHub.io retorna o seguinte JSON, que o código da custom code action mapeia diretamente para as propriedades do contato no HubSpot:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

7. Alternativa com webhook externo

Se seu plano HubSpot não suporta custom code, use a ação Webhook do workflow:

• Method — POST

• URL — Endpoint do seu servidor intermediário.

• Body — Envie o CPF do contato.

O servidor recebe o webhook, consulta a CPFHub.io e atualiza o contato via API do HubSpot:

const express = require('express');
const app = express();
app.use(express.json());

app.post('/webhook/hubspot', async (req, res) => {
    const { contactId, cpf } = req.body;
    const cpfLimpo = cpf.replace(/\D/g, '');

    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 5000);

    try {
    const cpfResponse = await fetch(`https://api.cpfhub.io/cpf/${cpfLimpo}`, {
    method: 'GET',
    headers: {
    'x-api-key': process.env.CPFHUB_API_KEY,
    'Accept': 'application/json'
    },
    signal: controller.signal
    });

    clearTimeout(timeoutId);
    const dados = await cpfResponse.json();

    if (dados.success) {
    await fetch(`https://api.hubapi.com/crm/v3/objects/contacts/${contactId}`, {
    method: 'PATCH',
    headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${process.env.HUBSPOT_TOKEN}`
    },
    body: JSON.stringify({
    properties: {
    cpf_nome_validado: dados.data.name,
    cpf_status: 'Validado',
    cpf_data_nascimento: dados.data.birthDate
    }
    })
    });
    }

    res.json({ success: true });
    } catch (error) {
    clearTimeout(timeoutId);
    res.status(500).json({ error: error.message });
    }
});

app.listen(3000);

8. Boas práticas

• Timeout — O exemplo usa timeout: 5000 no axios para evitar que a custom code action exceda o limite de execução do HubSpot. A API CPFHub.io responde em ~150 ms, mas o timeout protege contra instabilidades de rede.

• Secrets — Armazene a chave de API da CPFHub.io nos secrets do workflow (disponível em custom code actions).

• Volume — Em workflows com alto volume, monitore o consumo de cota. No plano Grátis, os 50 créditos mensais esgotados pausam as consultas e a API responde HTTP 403 com "Limite de créditos excedido". Nos planos pagos o excedente, quando o plano inclui, é cobrado na fatura seguinte — os valores estão na página de preços. O limite por minuto é separado: HTTP 429 com Retry-After.

• Branching — Adicione uma branch no workflow após a validação: se cpf_status = "Validado", continue o pipeline; se "Erro", envie notificação ao time.

• Logs — Use o histórico de execução do workflow para auditar consultas realizadas.

Perguntas frequentes

Qual plano do HubSpot é necessário para usar custom code actions em workflows?

É necessário o plano Professional ou Enterprise do HubSpot. Planos Starter não incluem a ação de custom code. Se sua empresa usa um plano mais básico, a alternativa é o webhook externo descrito na seção 7, que funciona com qualquer plano que suporte webhooks.

A API CPFHub.io bloqueia quando o limite de consultas gratuitas é atingido?

No plano Grátis, sim: ao acabar os 50 créditos do mês as consultas pausam e a API responde HTTP 403 com a mensagem "Limite de créditos excedido". Nos planos pagos pode haver excedente, cobrado na fatura seguinte pelo valor da página de preços. O limite por minuto é separado e devolve HTTP 429 com o header Retry-After.

Como evitar que um contato passe pelo workflow de validação mais de uma vez?

Adicione o filtro cpf_status is "Pendente" ou is unknown como condição de entrada no workflow. Após a validação, o campo é atualizado para "Validado" ou "Erro", impedindo que o contato seja processado novamente em execuções futuras.

É possível usar a validação de CPF no HubSpot para qualificar leads automaticamente?

Sim. Após a validação, adicione uma branch no workflow: leads com cpf_status = "Validado" recebem uma pontuação maior no lead scoring ou são movidos automaticamente para o pipeline de vendas. Leads com status "Erro" podem ser encaminhados para revisão manual ou receber um e-mail solicitando os dados corretos.

Conclusão

Integrar a validação de CPF da CPFHub.io no HubSpot via workflows customizados transforma um processo manual de conferência de dados em um fluxo automático: assim que o lead preenche o CPF, o workflow dispara, consulta a API e grava os dados validados nas propriedades do contato — sem intervenção humana.

O resultado prático é um pipeline mais limpo, com leads qualificados por dados verificados, e menos retrabalho do time de vendas com contatos incorretos ou fraudulentos. Comece agora com o plano gratuito: crie sua conta em cpfhub.io e tenha 50 consultas mensais disponíveis, sem cartão de crédito, para testar a integração com seu workflow HubSpot.