Boas Práticas

Recomendações para receber webhooks de forma robusta — responder rápido, validar assinatura, idempotência no receptor.

Responda rapidamente

O servidor do Minha CNH aguarda no máximo 10 segundos por uma resposta. Processe o webhook de forma assíncrona: responda 200 imediatamente e execute o processamento pesado numa queue ou worker.

app.post('/webhook', (req, res) => {
  res.status(200).send('queued');  // resposta imediata
  queue.push(req.body);            // processamento async
});

Valide sempre a assinatura

Nunca confie no conteúdo de um webhook sem verificar X-MinhaCNH-Signature. Um atacante pode enviar POSTs para o seu endpoint público com payloads falsos. Ver Verificar Assinatura.

Use um endpoint público com HTTPS

Recomendamos fortemente HTTPS com certificado válido. Por segurança, o Minha CNH só entrega para endpoints que resolvem para endereços públicos: URLs que apontam para faixas privadas, loopback ou metadata interna são bloqueadas na configuração e na entrega.

Implemente idempotência no receptor

Use X-MinhaCNH-Delivery como chave de deduplicação. Retries legítimos podem re-entregar o mesmo evento, e o seu receptor deve ser idempotente.

Trate `report.failed`

Quando o relatório falha após todas as tentativas do pipeline, o crédito é estornado e o evento report.failed é enviado. Implemente um handler para sinalizar a falha no seu sistema e, se necessário, re-submeter o relatório.

Não dependa apenas de webhooks

Implemente também polling periódico em GET /api/v1/reports/{reportId} como fallback. Se o seu servidor de webhook estiver indisponível durante todas as tentativas, o polling garante que você não perde o resultado do relatório.