Webhooks
Receba o resultado de um relatório assim que ele fica pronto, sem ficar consultando a API: como assinar, verificar a origem e tratar reentrega.
O que são os webhooks
Quando um relatório atinge um estado terminal, o Minha CNH faz um POST para a URL que você
configurou em Configurações → API. O corpo contém o mesmo shape do endpoint de polling.
Eventos
| Evento | Quando ocorre |
|---|---|
report.delivered | Pipeline completou e o diagnóstico está disponível |
report.partially_delivered | Relatório entregue, mas dados complementares da consulta estadual ficaram pendentes. Se a busca for recuperada depois, um report.delivered é enviado em seguida |
report.failed | Pipeline falhou após todas as tentativas; crédito estornado |
O corpo do `report.partially_delivered` não vem vazio
Esse evento carrega status: "PROCESSING" — porque a consulta estadual ainda pode responder — e
já traz diagnosis e details preenchidos com o que foi apurado.
Um handler que faz if (payload.status !== "DELIVERED") return; descarta um relatório que tem dado.
Teste diagnosis !== null / details !== null para saber se há o que ler, e o status para saber
se ainda vem um report.delivered depois.
Headers enviados
| Header | Valor exemplo |
|---|---|
Content-Type | application/json |
X-MinhaCNH-Event | report.delivered |
X-MinhaCNH-Delivery | id único por entrega |
X-MinhaCNH-Signature | t=1748785200,v1=<hex-sha256> |
User-Agent | MinhaCNH-Webhook/1.0 |
Fluxo de entrega
- Relatório atinge um estado terminal (
DELIVERED,PARTIALLY_DELIVEREDouERROR). - Um registro de entrega é criado com a URL do webhook snapshotada nesse instante.
- Um cron de 1 minuto faz o
POSTpara a URL, com a assinatura recomputada por tentativa. - Resposta
2xx→ entrega marcada comoDELIVERED. - Resposta não-2xx ou timeout → backoff exponencial (ver Retries e Backoff).