Webhooks
Em vez de consultar a API de tempos em tempos, receba um aviso no seu sistema quando algo acontece no Nottun.
Consultar a API de minuto em minuto para descobrir se algo mudou é caro e lento. O webhook inverte isso: o Nottun avisa o seu sistema quando o evento acontece.
Onde cadastrar
No painel, em Negócio, Integrações, Webhooks. Cada webhook tem um nome, um endereço de destino e a lista de eventos que ele escuta.
O endereço precisa ser https. A entrega leva dados da vistoria e a assinatura no cabeçalho, e em texto claro entregaria os dois a quem estiver no caminho.
Quais eventos existem
- Vistoria disponibilizada: a vistoria foi validada e o laudo ficou disponível.
- Laudo assinado digitalmente: todas as partes assinaram e o documento foi finalizado.
- Contestação concluída: o responsável terminou de contestar a vistoria.
- Contestação respondida pelo negócio: o negócio respondeu cada item contestado e fechou a rodada.
O segredo e a assinatura
Ao criar o webhook, a Nottun gera um segredo e o exibe uma única vez. É com ele que o seu sistema confere que a entrega veio mesmo da Nottun.
Cada entrega chega com três cabeçalhos: o evento, o instante do envio e a assinatura, que é o resultado de aplicar o segredo sobre o instante e o corpo da requisição. O seu sistema refaz essa conta e compara.
Se perder o segredo, use a ação de gerar um novo segredo na listagem. O anterior deixa de valer na hora, então atualize o seu sistema antes da próxima entrega.
Entrega de teste
Você não precisa esperar uma vistoria de verdade ficar pronta para saber se o endereço responde. A ação de enviar uma entrega de teste dispara uma entrega imediata, marcada como tal, que aparece no histórico como qualquer outra.
Acompanhar as entregas
A ação de ver as entregas abre o histórico do webhook, com a situação de cada envio, o código que o seu sistema respondeu, quantas tentativas houve e o conteúdo exato que foi enviado.
Isso responde à pergunta que toda integração faz mais cedo ou mais tarde: o aviso foi enviado e o meu sistema não processou, ou ele nunca chegou?
Uma entrega recusada é tentada de novo automaticamente, até quatro vezes, com intervalos crescentes. Ela só é marcada como falha quando as tentativas terminam. Você também pode reenviar qualquer entrega à mão.
Desligar sem apagar
Um webhook pode ser desativado direto na listagem. Enquanto estiver assim, nenhuma entrega é enviada para aquele endereço, e o histórico continua lá. É o caminho certo quando o sistema que recebe está em manutenção: remover o webhook apagaria o histórico junto.
Onde está a referência técnica
Os cabeçalhos, o formato do corpo, os campos que cada evento entrega e um exemplo pronto de conferência da assinatura estão em documentacao.nottun.com, na seção Webhooks.
O que o seu sistema precisa fazer
- Responder rápido. Processamento demorado deve acontecer depois de confirmar o recebimento, e não durante ele.
- Ser idempotente. Um mesmo evento pode chegar mais de uma vez, e processar duas vezes não pode gerar dois registros.
- Aceitar campos novos sem quebrar. A carga do evento pode ganhar informação com o tempo.
Requisito de plano
Os webhooks fazem parte do mesmo recurso de plano que a API. Sem ele, nenhuma entrega é enviada, e a tela avisa isso antes de você cadastrar um webhook novo.