Para validar um webhook assinado em integração com o ERP, recalcule a assinatura com o corpo bruto e o segredo, compare e só então processe. Duplicidade e perda se resolvem com identificador de evento e uma rotina de reprocessamento.
Como validar webhook assinado: a conferência da assinatura
A assinatura prova duas coisas: que o evento veio de quem você espera e que ninguém alterou o conteúdo no caminho. Sem essa conferência, qualquer um que descubra a URL pode mandar um "pedido faturado" falso.
- Corpo bruto. Use os bytes exatamente como chegaram. Se você reformatar o JSON antes de calcular, a assinatura nunca vai bater.
- Recálculo. Gere a assinatura com o segredo compartilhado e o algoritmo combinado com o emissor.
- Comparação segura. Use comparação em tempo constante, não a comparação comum de texto.
- Janela de tempo. Se o evento traz data de envio, rejeite os muito antigos para barrar reaproveitamento.
- Resposta clara. Assinatura inválida volta como erro e não entra em nenhuma fila.
Guarde o segredo fora do código e tenha um plano para trocá-lo sem derrubar a integração, por exemplo aceitando o segredo antigo e o novo por um período curto.
Duplicidade: o mesmo evento vai chegar mais de uma vez
Quem envia webhook reenvia quando não recebe resposta a tempo. Então a duplicidade é rotina, não exceção.
Grave o identificador de cada evento ao receber. Se ele já existe, responda sucesso e não faça nada. Imagine um evento de entrega confirmada que chega duas vezes: sem essa trava, o ERP registraria a baixa em dobro. O tema é irmão do que explicamos em integrar portal e ERP sem dor.
Responda rápido e processe depois. Receba, valide, grave na fila e devolva a resposta; o trabalho pesado no ERP roda em seguida.
Reprocessar eventos perdidos
Eventos se perdem: o ERP ficou fora do ar, o emissor desistiu de reenviar, houve erro seu. Você precisa conseguir buscar de novo o que faltou.
- Registro de tudo. Guarde cada evento recebido com situação: recebido, processado ou com falha.
- Separação de erros. Falha técnica pode ser tentada de novo; falha de regra de negócio pede correção antes. Veja como separar os dois.
- Reprocesso manual. Uma tela ou rotina para reenviar um evento específico, sem mexer no banco.
- Conciliação. Periodicamente, compare o que o ERP tem com o que o emissor diz ter enviado e reprocesse a diferença.
Como o evento já tem identificador, reprocessar é seguro: se ele já foi aplicado, nada se repete.
Quando isso já vem pronto
No Routkey, o conector para o ERP, a API aberta e os webhooks assinados cobrem a ponta da entrega. Você ainda decide como seu ambiente recebe, valida e reprocessa.
Posso confiar só em um IP fixo em vez da assinatura?
Não. IP ajuda como camada extra, mas muda e pode ser falsificado em certos cenários. A assinatura valida o conteúdo e a origem.
Devo responder erro quando o evento for duplicado?
Não. Responda sucesso, para o emissor parar de reenviar, e ignore o processamento.
Para o próximo passo, pegue a integração que você tem hoje e confira três pontos: se a assinatura é validada sobre o corpo bruto, se o identificador do evento é gravado e se existe um jeito de reprocessar um evento sem ajuda de quem programou.