# Como configurar webhooks para notificações em consultas de CPF > Aprenda a configurar webhooks para receber notificações automáticas sobre consultas de CPF. Arquitetura event-driven para validação de identidade. **Publicado:** 18/04/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-configurar-webhooks-para-notificacoes-em-consultas-de-cpf --- Para configurar webhooks em consultas de CPF, você precisa de um endpoint HTTPS na sua aplicação que receba notificações POST, valide a assinatura HMAC-SHA256 do payload e responda com HTTP 200 em menos de 5 segundos. No lado do remetente, um worker consulta a API da CPFHub.io, assina o resultado e envia para o seu endpoint — eliminando a necessidade de polling e tornando o fluxo totalmente event-driven. Em arquiteturas modernas, nem sempre é viável esperar a resposta de uma consulta de CPF de forma síncrona. Processos como onboarding em lote, revalidação periódica e monitoramento exigem uma abordagem assíncrona. **Webhooks** permitem que sua aplicação receba notificações automáticas quando uma consulta é concluída, sem precisar ficar fazendo polling. --- ## O que é um webhook Um webhook é uma chamada HTTP que o sistema faz para a sua aplicação quando um evento ocorre. Em vez de sua aplicação perguntar "já terminou?" repetidamente (polling), o sistema avisa quando o resultado está pronto. | Polling | Webhook | | --- | --- | | Sua app pergunta repetidamente | O sistema avisa quando pronto | | Consome recursos desnecessários | Eficiente e event-driven | | Latência variável | Notificação imediata | | Complexo de escalar | Escala naturalmente | --- ## Arquitetura com webhooks para consultas de CPF ``` 1. [Sua App] → Envia CPF para processamento 2. [Worker] → Consulta API da CPFHub.io 3. [Worker] → Recebe resposta 4. [Worker] → Envia resultado via webhook para [Sua App] 5. [Sua App] → Processa o resultado ``` --- ## Implementação do servidor webhook ### Endpoint para receber notificações ```python from flask import Flask, request, jsonify import hmac import hashlib app = Flask(__name__) WEBHOOK_SECRET = 'SEU_WEBHOOK_SECRET' @app.route('/webhook/cpf', methods=['POST']) def receber_webhook(): # Verificar assinatura assinatura = request.headers.get('X-Webhook-Signature') payload = request.get_data() esperado = hmac.new( WEBHOOK_SECRET.encode(), payload, hashlib.sha256 ).hexdigest() if not hmac.compare_digest(assinatura or '', esperado): return jsonify({'error': 'Assinatura invalida'}), 401 dados = request.json # Processar resultado cpf_hash = dados.get('cpf_hash') resultado = dados.get('resultado') status = dados.get('status') print(f'Webhook recebido: CPF {cpf_hash} - Status: {status}') # Atualizar banco de dados, notificar usuario, etc. return jsonify({'received': True}), 200 ``` ### Worker que processa consultas e envia webhooks ```python import requests import hashlib import hmac import json def processar_e_notificar(cpf: str, webhook_url: str, secret: str): # 1. Consultar API url = f'https://api.cpfhub.io/cpf/{cpf}' headers = { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' } response = requests.get(url, headers=headers, timeout=10) resultado = response.json() # 2. Preparar payload do webhook payload = { 'cpf_hash': hashlib.sha256(cpf.encode()).hexdigest(), 'status': 'encontrado' if resultado.get('success') else 'nao_encontrado', 'resultado': resultado.get('data', {}) } payload_bytes = json.dumps(payload).encode() # 3. Assinar payload assinatura = hmac.new( secret.encode(), payload_bytes, hashlib.sha256 ).hexdigest() # 4. Enviar webhook requests.post( webhook_url, json=payload, headers={ 'Content-Type': 'application/json', 'X-Webhook-Signature': assinatura }, timeout=10 ) ``` --- ## Boas práticas para webhooks ### 1. Sempre valide a assinatura Use HMAC-SHA256 para garantir que o webhook veio de uma fonte confiável e não foi adulterado. O [OWASP](https://owasp.org) recomenda essa validação de assinatura como controle essencial para qualquer endpoint que receba dados via callback — sem ela, qualquer agente externo pode injetar payloads falsos no seu sistema. ### 2. Responda rápido (< 5 segundos) O endpoint webhook deve processar a requisição rapidamente. Se precisar de processamento pesado, enfileire internamente e responda com 200 imediatamente. ### 3. Implemente idempotência Webhooks podem ser enviados mais de uma vez. Use um ID único para cada evento e verifique se já foi processado. ### 4. Configure retries Se o endpoint estiver fora do ar, implemente retry com backoff exponencial no lado do remetente. ### 5. Use HTTPS O endpoint webhook deve aceitar apenas HTTPS para proteger os dados em trânsito. --- ## Casos de uso * **Onboarding em lote** -- Processar centenas de CPFs e receber resultados via webhook. * **Revalidação periódica** -- Agendar revalidação de CPFs e receber notificações sobre mudanças. * **Monitoramento** -- Alertas quando uma consulta falha ou retorna dados inesperados. * **Integração com CRM** -- Atualizar fichas de clientes automaticamente após validação. --- ## Perguntas frequentes ### Como o webhook sabe que a notificação de CPF é legítima? A autenticidade é garantida por uma assinatura HMAC-SHA256 gerada a partir do payload e de um segredo compartilhado. O seu endpoint recalcula a assinatura usando o mesmo segredo e compara com o header `X-Webhook-Signature`. Se não baterem, a requisição deve ser rejeitada com HTTP 401 — isso impede que terceiros injetem notificações falsas. ### O que acontece se meu endpoint de webhook estiver fora do ar? O worker responsável pelo envio deve implementar retry com backoff exponencial: tenta novamente após 30 segundos, depois 2 minutos, depois 10 minutos, e assim por diante. Além disso, implemente idempotência no seu endpoint usando o ID único do evento — assim, se o webhook chegar duplicado após uma falha temporária, você processa apenas uma vez. ### Qual é a latência da API da CPFHub.io usada dentro do worker? A API da CPFHub.io responde em aproximadamente 900ms em condições normais. No fluxo assíncrono com webhook, essa latência não impacta a experiência do usuário final, pois o processamento ocorre em background e o resultado é entregue via notificação assim que o worker conclui a consulta. ### Webhooks funcionam bem para onboarding em lote de CPFs? Sim, é o modelo ideal para esse caso. Em vez de disparar centenas de chamadas síncronas e aguardar cada resposta, o worker enfileira os CPFs, consulta a API da CPFHub.io em sequência e envia um webhook para cada resultado concluído. Sua aplicação processa as notificações conforme chegam, sem bloquear threads e sem risco de timeout no cliente. ### Leia também - [Como implementar retry e backoff exponencial em consultas de API de CPF](https://cpfhub.io/blog/como-implementar-retry-backoff-exponencial-consultas-api-cpf) - [Como implementar cache inteligente em respostas de API de CPF](https://cpfhub.io/blog/como-implementar-cache-inteligente-respostas-api-cpf) - [SLA de API de CPF: níveis de disponibilidade](https://cpfhub.io/blog/sla-api-cpf-niveis-disponibilidade) - [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos) --- ## Conclusão Webhooks são a forma mais eficiente de receber resultados de consultas de CPF em cenários assíncronos. Combinados com a API da [**CPFHub.io**](https://www.cpfhub.io/) — que responde em ~900ms e nunca bloqueia por volume, cobrando apenas R$0,15 por consulta excedente — você monta uma arquitetura event-driven robusta com poucos dias de desenvolvimento. O padrão de assinar o payload com HMAC-SHA256, responder com 200 rapidamente e enfileirar o processamento pesado é suficiente para a maioria dos casos de uso. Se o seu volume crescer, a mesma arquitetura escala horizontalmente sem alterar o contrato da API. Comece com o plano gratuito (50 consultas/mês, sem cartão) e evolua conforme sua demanda. Crie sua conta em [cpfhub.io](https://www.cpfhub.io/) e configure seu primeiro webhook em menos de uma hora.