API de monitoramento de CNPJ: eventos, webhooks e CloudEvents

A maioria das integrações com dados de CNPJ nasce igual: um job que consulta uma API de consulta para cada empresa da base, compara com o que está no banco e tenta descobrir o que mudou. Funciona no protótipo — e vira um problema de engenharia conforme a carteira cresce: rate limits, custo por consulta, diffs frágeis e a pergunta sem resposta boa: "com que frequência a gente re-consulta?".

Este artigo mostra a alternativa: consumir uma API de monitoramento de CNPJ orientada a eventos — o que muda no modelo, como é a anatomia de um evento societário no padrão CloudEvents v1.0 e as boas práticas para receber webhooks em produção.

Consulta (pull) vs. eventos (push)

No modelo pull, a detecção de mudanças é problema seu: você agenda consultas, armazena estados e calcula diferenças. No modelo push, a detecção é do provedor: o seu sistema recebe apenas o fato relevante — "o QSA da empresa X mudou às 14h32, de A para B".

Anatomia de um evento societário (CloudEvents v1.0)

O CloudEvents é uma especificação da CNCF que padroniza o envelope de eventos: os mesmos atributos (id, source, type, time, subject, data) independentemente do transporte. Usar um padrão aberto significa que o evento entra direto em ferramentas que já falam CloudEvents — brokers, funções serverless, pipelines — sem parser proprietário.

Um evento de alteração de quadro societário emitido pela Timeax tem esta forma:

{
  "specversion": "1.0",
  "id": "evt_01j9x7k2m3",
  "source": "https://timeax.tech/monitoring",
  "type": "tech.timeax.company.qsa.changed",
  "subject": "cnpj:12345678000190",
  "time": "2026-07-07T14:32:08Z",
  "datacontenttype": "application/json",
  "data": {
    "cnpj": "12.345.678/0001-90",
    "field": "qsa",
    "before": [
      { "nome": "MARIA SILVA", "qualificacao": "Sócio-Administrador" },
      { "nome": "JOÃO SOUZA", "qualificacao": "Sócio" }
    ],
    "after": [
      { "nome": "MARIA SILVA", "qualificacao": "Sócio-Administrador" },
      { "nome": "CARLOS PEREIRA", "qualificacao": "Sócio" }
    ],
    "diff": {
      "added": [{ "nome": "CARLOS PEREIRA", "qualificacao": "Sócio" }],
      "removed": [{ "nome": "JOÃO SOUZA", "qualificacao": "Sócio" }]
    }
  }
}

Três decisões de design valem destacar: o type é hierárquico e filtrável (company.qsa.changed, company.status.changed, company.capital.changed…); o subject identifica a entidade monitorada, permitindo roteamento sem abrir o payload; e o data carrega antes, depois e diff — o consumidor não precisa manter estado próprio para saber o que mudou.

Boas práticas para receber webhooks

Valide a assinatura

Todo webhook sério assina as entregas (tipicamente HMAC do corpo com um segredo compartilhado, enviado em um header). Rejeite requisições com assinatura inválida — o endpoint é público e receberá tráfego que não é do provedor.

Responda rápido, processe depois

Confirme o recebimento (HTTP 2xx) imediatamente e delegue o processamento a uma fila. Endpoints que processam de forma síncrona estouram timeout, provocam retries e criam duplicatas.

Seja idempotente

Entregas de webhook são tipicamente *at-least-once*: em caso de falha de rede, o mesmo evento pode chegar duas vezes. Use o id do CloudEvent como chave de deduplicação antes de disparar qualquer ação de negócio.

Não dependa da ordem

Retries e paralelismo podem inverter a ordem de chegada. Use o atributo time do evento (momento da detecção) — não o horário de recebimento — para ordenar a linha do tempo de uma empresa.

Tenha um plano de recuperação

Se o seu endpoint ficar fora do ar, os eventos do período precisam ser recuperáveis. É o papel do endpoint REST de listagem (GET /v1/events, com filtros por período e por CNPJ): reconciliar o que os webhooks eventualmente perderam.

Para onde levar os eventos

• Workflow de compliance — qsa.changed reabre o caso de KYC do cliente automaticamente (due diligence contínua);
• Motor de crédito — capital.changed e status.changed recalculam score e limite do CNPJ (mudanças de situação cadastral);
• CRM/ERP — endereço e CNAE atualizam o cadastro mestre sem redigitação;
• Data warehouse — a linha do tempo de eventos vira tabela fato para modelos e análises;
• Alertas operacionais — conectores para Slack/Teams notificam o dono do contrato no canal onde ele já trabalha.

O panorama completo do que monitorar — e por quê — está no nosso guia de monitoramento de CNPJ. Para conhecer os canais de entrega da Timeax (painel, GET /v1/events e webhooks CloudEvents), veja a página do produto.