Um fornecedor avisa que um pedido mudou de estado. Seu sistema recebe o webhook, mas precisa atualizar o estoque, registrar o histórico e avisar outra área. Essas etapas têm tempos e possibilidades de falha diferentes. Projetar apenas a URL que recebe a notificação deixa boa parte da integração sem resposta.
Verifique a origem antes de agir
Use o mecanismo de assinatura ou autenticação definido pelo fornecedor e valide a mensagem antes de processá-la. Uma URL difícil de adivinhar não substitui essa verificação. Guarde segredos fora do código e planeje como trocá-los quando necessário.
Confira também o tipo de evento e os campos obrigatórios. Uma mensagem válida do ponto de vista de origem ainda pode não corresponder a uma operação que sua aplicação reconhece.
Registre a entrega antes de confirmar
Para trabalhos demorados, uma abordagem possível é guardar o evento de forma durável e encaminhá-lo para processamento separado. Assim, a resposta ao fornecedor não precisa esperar todas as etapas internas. A confirmação deve corresponder ao que realmente foi garantido: aceitar a mensagem é diferente de concluir seu efeito.
Os limites de tempo e os significados das respostas variam por fornecedor. Consulte o contrato da integração, em vez de supor que todos reenviam eventos da mesma maneira.
Espere duplicatas e mudanças de ordem
Uma entrega pode ser repetida após falha ou reenvio manual. Use um identificador estável do evento, quando disponível, para reconhecer o que já foi tratado. A proteção contra duplicação deve abranger a alteração de negócio, além do recebimento da mensagem.
Também confira se o fornecedor garante ordem. Se um estado antigo chegar depois de um novo, o sistema precisa evitar uma regressão incorreta. Versões do registro, horários definidos pelo contrato ou uma consulta ao estado atual podem ajudar, conforme o caso.
Tenha um caminho de investigação
- Relacione o identificador do evento ao registro alterado.
- Mostre se o processamento está pendente, concluído ou com falha.
- Permita reprocessar com as mesmas proteções contra duplicação.
- Defina quem acompanha mensagens que excederam o limite de tentativas.
Nos registros de diagnóstico, evite expor segredos ou guardar dados desnecessários. O histórico deve permitir entender o percurso da operação sem transformar cada log em uma cópia completa de informações sensíveis.
Teste o caminho que dá errado
Simule mensagens repetidas, assinaturas inválidas, campos ausentes e falhas após o recebimento. Essas verificações mostram se a integração consegue recuperar o trabalho, além de receber um evento em uma demonstração.
Leitura complementar: boas práticas de webhooks do GitHub, um exemplo de contrato de fornecedor.
