Como configurar webhooks para notificações 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.

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

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

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 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.

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 — 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 e configure seu primeiro webhook em menos de uma hora.