Pular para o conteúdo
DADOS DECNPJ

Webhooks

Seu sistema recebe os eventos do Dados de CNPJ na hora, com entrega assinada e retentativas.

Cadastrar endpointVoltar à API

Eventos, sem consultar

Um POST JSON no seu servidor quando algo acontece. Até 5 endpoints no plano Corporativo.

Assinatura HMAC-SHA256

Cada entrega leva timestamp e assinatura com o segredo do endpoint.

Retentativas

Sem 2xx, tentamos de novo com espera crescente (1 min a 6 h).

Como funciona

  1. Em Painel › API › Webhooks, cadastre uma URL https pública e escolha os eventos.
  2. Copie o segredo (whsec_…). Ele aparece uma vez; se perder, troque por outro no painel.
  3. No seu servidor, verifique a assinatura com o corpo bruto, responda 2xx em até 5 segundos e processe o evento depois.
  4. Use “Enviar teste” no painel para conferir: chega um evento webhook.test.

Eventos

dataset.published
Base nova publicada: Saiu uma competência nova da Receita Federal.
company.changed
Empresa monitorada mudou: Mudança cadastral numa empresa que você monitora.
export.completed
Exportação concluída: Uma planilha ficou pronta para baixar.

Corpo da entrega

Todo evento usa o mesmo envelope; data muda conforme o evento. Nenhum dado pessoal vai no corpo.

{
  "id": "0193f0c2-7a51-7c1e-9d0e-5b2f3c4d5e6f",
  "event": "dataset.published",
  "created_at": "2026-11-06T09:12:00-03:00",
  "test": false,
  "data": {
    "version": "2026_11",
    "previous_version": "2026_10",
    "competence": "2026-11",
    "published_at": "2026-11-06T09:11:58-03:00"
  }
}

Verificar a assinatura

O cabeçalho X-Ddc-Signature traz t (timestamp Unix) e v1 = HMAC-SHA256, em hexadecimal, de {t}.{corpo bruto} com o segredo do endpoint.

  1. Leia o corpo exatamente como chegou (antes de converter o JSON).
  2. Recuse se t estiver a mais de 5 minutos do seu relógio (evita reenvio de uma entrega capturada).
  3. Calcule o HMAC e compare com v1 em tempo constante.
  4. Guarde o id: numa retentativa, o mesmo evento pode chegar de novo.

Cabeçalhos

X-Ddc-Signature
t=<unix>,v1=<hmac hex>: assinatura da entrega.
X-Ddc-Event
Nome do evento (ex.: dataset.published).
X-Ddc-Delivery
Id único da entrega (o mesmo do campo id do corpo). Use para ignorar repetidas.
X-Ddc-Timestamp
O mesmo t da assinatura, em segundos Unix.
Content-Type
application/json

Verificação da assinatura

# Simula uma entrega assinada para testar o seu endpoint (precisa de openssl).
BODY='{"id":"teste","event":"webhook.test","created_at":"2026-11-06T12:00:00-03:00","test":true,"data":{}}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$DDC_WEBHOOK_SECRET" | sed 's/^.* //')
curl -s -X POST https://seu-servidor.com.br/webhooks/ddc \
  -H "Content-Type: application/json" \
  -H "X-Ddc-Signature: t=$TS,v1=$SIG" \
  -d "$BODY"

Na aba curl: simula uma entrega assinada para testar o seu endpoint.

Entregas, retentativas e desativação

  • Sucesso é qualquer resposta 2xx. Redirecionamentos não são seguidos.
  • Sem 2xx (ou sem resposta em 5 s), tentamos de novo após 1 min, 5 min, 30 min, 2 h e 6 h: 6 tentativas no total.
  • Depois de 10 entregas seguidas sem sucesso, o endpoint é desativado e avisado no painel. Corrija e reative.
  • O log de entregas (status HTTP, tempo, trecho da resposta) fica 30 dias no painel.

Segurança do destino

  • Só URLs https, sem usuário e senha na URL.
  • O endereço precisa ser público: IPs privados, de loopback, link-local e de metadados de nuvem são recusados no cadastro e de novo a cada entrega.
  • Quer restringir por IP no seu firewall? Prefira validar a assinatura: os IPs de saída podem mudar.