Webhook do monitoramento

O que você vai aprender

Você vai cadastrar o endereço do seu sistema que recebe os avisos, testar o envio, conferir a assinatura de cada aviso e acompanhar os envios: os que deram certo, os que falharam e as novas tentativas.

Quando usar

• Quando o seu sistema de gestão, CRM ou ferramenta de automação (como Zapier, Make ou n8n) precisa reagir sozinho a uma mudança num cliente ou fornecedor, por exemplo bloqueando um pedido quando a empresa fica inapta.
• Quando a equipe de TI quer guardar o histórico de mudanças no próprio banco de dados.
• Se você só precisa ler os avisos, não precisa do webhook: eles já chegam por e-mail e na Carteira monitorada.

Antes de começar

• Tenha um endereço https no seu sistema que aceite um POST com conteúdo JSON e responda com um código de sucesso (200 a 299) em até 15 segundos.
• Para experimentar antes de mexer no seu sistema, use um endereço de teste, como os do webhook.site, e troque pelo definitivo depois.
• Os avisos de verdade pelo webhook são dos planos pagos. No plano Grátis, só o envio de teste sai.

Passo a passo

1. Abra o bloco do webhook. Na Carteira monitorada, role até o fim da página e clique em Webhook: receber os avisos no seu sistema (opcional) (1). O bloco abre logo abaixo.

   

2. Cadastre o endereço. Em URL (https) (1), digite o endereço que vai receber os avisos, por exemplo https://seusistema.com.br/webhooks/cnpjone.

   

3. Salve e teste. Clique em Salvar e testar (2). O sistema grava o endereço e manda na hora um aviso de teste, com "evento": "teste", sem esperar mudança em nenhuma empresa. Aparece "Webhook salvo e testado com sucesso." ou "Webhook salvo, mas o teste falhou: o endereço não confirmou o recebimento. Confira a URL com quem cuida do seu sistema.". Se preferir só gravar, clique em Salvar.

4. Guarde o segredo. No primeiro salvamento, aparece o quadro "Segredo do webhook (exibido só agora):", com um código que começa com whsec_. Copie e guarde no seu sistema: ele não aparece de novo. É com ele que o seu sistema confere a assinatura de cada aviso.

5. Confira a assinatura no seu sistema. Cada aviso chega com o cabeçalho X-CNPJOne-Assinatura (3), no formato sha256= seguido do código HMAC-SHA256 do corpo da mensagem, calculado com o seu segredo. O seu sistema calcula o mesmo código com o corpo recebido e o segredo guardado e compara. Se for diferente, descarte o aviso. Exemplo em PHP:

   $corpo = file_get_contents('php://input');
   $esperado = 'sha256=' . hash_hmac('sha256', $corpo, 'SEU_SEGREDO');
   if (! hash_equals($esperado, $_SERVER['HTTP_X_CNPJONE_ASSINATURA'] ?? '')) {
       http_response_code(401);
       exit;
   }
   $aviso = json_decode($corpo, true);
   

6. Acompanhe os envios. Abaixo dos botões, o quadro do último envio diz quando foi, se era teste ou aviso de alterações e se o seu servidor recebeu, com o código da resposta. Em Últimos envios, aparecem os 10 envios mais recentes: os recebidos têm um sinal de confirmação; os que falharam têm um ponto vermelho, o código ou "sem resposta", quantas tentativas já foram feitas e a hora da próxima. Para mandar de novo na hora, clique em Reenviar, na linha do envio que falhou.

7. Troque o segredo, se precisar. Se o segredo se perdeu ou vazou, clique em Gerar novo segredo e confirme. O anterior deixa de valer na hora: atualize o seu sistema com o novo. O botão só fica ativo quando o endereço do campo é o mesmo que está salvo.

O que acontece depois

• Quando os avisos saem. Uma vez por dia, depois da verificação da noite, e só quando alguma empresa da carteira mudou. Um único envio junta todas as mudanças da noite.

• O que é enviado. Um POST em JSON, assim:

  {
    "evento": "alteracoes",
    "origem": "monitoramento",
    "referencia": "2026-10-23",
    "alteracoes": [
      {
        "cnpj": "12345678000190",
        "apelido": "Fornecedor de exemplo",
        "campo": "divida_inscricoes",
        "rotulo": "Inscrições em dívida ativa",
        "anterior": "0",
        "novo": "2"
      }
    ]
  }
  

  referencia é a data da verificação. Em cada alteração, cnpj vem só com os números, apelido é o que você deu à empresa (ou vazio), campo é o código do que mudou, rotulo é o texto que aparece no painel e no e-mail, e anterior e novo são os valores antes e depois. As mudanças do cadastro da Receita podem vir sem rotulo; nelas, campo é o nome do dado, como situacao_cadastral ou endereco.

• Outros eventos no mesmo endereço. Se você tem pesquisas salvas na prospecção com aviso de empresas novas, o mesmo endereço recebe também "evento": "empresas_novas". Por isso, o seu sistema deve olhar o campo evento antes de tratar o aviso.

• Reenvio automático. Se o seu servidor não responder com sucesso, o aviso é enviado de novo sozinho depois de 1 minuto, 5 minutos, 30 minutos e 2 horas, no total de 5 tentativas. O envio de teste não é repetido.

• Avisos repetidos. O cabeçalho X-CNPJOne-Envio traz o número do aviso, que é o mesmo em todas as tentativas e no Reenviar. Use-o para ignorar um aviso que o seu sistema já recebeu.

• Assinatura nas novas tentativas. Cada tentativa é assinada com o segredo válido no momento do envio. Se você gerou um segredo novo, as tentativas seguintes já vêm com ele.

• O e-mail continua. Mesmo quando o webhook falha, os avisos chegam por e-mail e aparecem na Carteira monitorada.

Dicas e erros comuns

• "O servidor respondeu com o código (número); esperamos um código 2xx (por exemplo, 200).": o endereço existe, mas o seu sistema recusou ou deu erro. Confira o log do seu servidor.
• "O servidor não respondeu em 15 segundos.": responda primeiro com 200 e faça o trabalho pesado depois, em segundo plano.
• "Não foi possível conectar ao endereço (confira a URL, o certificado https e se o servidor aceita conexões externas).": confira se o endereço está certo, se o certificado https é válido e se o firewall aceita conexões de fora.
• O endereço precisa começar com https://. Endereço com http:// não é aceito.
• Para parar de receber, apague o endereço do campo URL (https) e clique em Salvar.
• Ao trocar o endereço, o quadro do último envio é zerado. Use Salvar e testar para conferir o endereço novo.
• O sistema guarda os 50 envios mais recentes da conta.