# Como integrar validação de CPF em HubSpot com workflows customizados > Aprenda a integrar a API de consulta de CPF da CPFHub.io no HubSpot usando workflows customizados, custom code actions e webhooks. **Publicado:** 21/02/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-integrar-validacao-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](https://developers.hubspot.com/docs/api/crm/contacts) 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**](https://www.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: ```javascript 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**](https://www.cpfhub.io/) retorna o seguinte JSON, que o código da custom code action mapeia diretamente para as propriedades do contato no HubSpot: ```json { "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: ```javascript 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 ~900ms, 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. Para mais de 50 validações por mês, o plano Pro (1.000 consultas/mês por R$149) é mais econômico do que pagar R$0,15 por consulta excedente a partir da 51ª. * **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? Não. Ao atingir as 50 consultas mensais do plano gratuito, a API continua respondendo normalmente e cobra R$0,15 por consulta adicional. Não há bloqueio nem interrupção do workflow — o HubSpot nunca recebe um erro por limite de cota. ### 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. ### Leia também - [Como consumir API de CPF em Pipedrive para validação de leads](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-pipedrive-para-validacao-de-leads) - [Como integrar validação de CPF em Monday.com com automações](https://cpfhub.io/blog/como-integrar-validacao-de-cpf-em-monday-com-automacoes) - [SLA de API de CPF: níveis de disponibilidade e o que exigir do seu provedor](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) --- ## Conclusão Integrar a validação de CPF da [**CPFHub.io**](https://www.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](https://www.cpfhub.io/) e tenha 50 consultas mensais disponíveis, sem cartão de crédito, para testar a integração com seu workflow HubSpot.