IOSOR

IOSOR Guias

Assinatura do webhook e janela de replay: idempotência para que 02:00 seja entediante

Verifiquem assinaturas, limitem a janela de replay e tornem webhooks de entrada idempotentes — nunca aceitem callbacks sem assinatura, nunca debitam prepaid duas vezes num retry.

Callbacks sem assinatura não são eventos reais, mas sim tráfego HTTP não autenticado que apenas simula a sua carga de dados. Equipes que processam a requisição antes de validar a autenticidade enfrentam falhas críticas às 02:00, como débitos duplicados e confirmações repetidas que o financeiro não consegue estornar. A proteção definitiva exige a validação estrita da assinatura em cada chamada, uma janela de repetição curta e chaves de idempotência vinculadas diretamente ao razão contábil. Estruture uma operação resiliente com webhooks e chaves no lançamento e adote práticas para ter webhooks que sobrevivem ao lançamento.

Callbacks sem assinatura não são eventos

Verifiquem a assinatura antes de parsear campos de negócio. Rejeitem assinaturas em falta, caducadas ou desalinhadas com um erro client-safe — não processem «na mesma para o piloto». Um consumidor de staging que salta a verificação treina a produção a saltá-la. Catálogo live de mensagens não significa que o vosso URL de webhook é um lixão público.

Janelas de replay e por que 02:00 acontece

A entrega pelo-menos-uma-vez retenta em timeout, 5xx e perda de rede ambígua. Um retry tardio às 02:00 é normal. A janela limita quanto tempo um payload assinado continua aceitável: demasiado larga e um atacante rejogará um STOP velho; demasiado estreita e um retry legítimo parece falsificação. Registem rejeições de janela à parte de falhas de assinatura.

Idempotência que finanças consegue ler

O mesmo ID de evento deve produzir o mesmo estado final. Extraíam o ID de evento/mensagem da plataforma — não inventem uma chave com carimbo mais corpo. Devolvam sucesso num ID conhecido sem voltar a debitar. Envios de saída precisam da mesma disciplina — idempotência, retries e dinheiro.

Rotação de assinatura sem caos de dupla aceitação

Rotacionem segredos sem uma janela em que assinaturas velhas e novas são aceites para sempre. Planifiquem sobreposição, depois cortem. Nunca colem um segredo de produção num ticket. Separem consumidores de sandbox e produção. Dead-letter com ferramentas de replay para ops reconduzir um consumidor falhado sem inventar um segundo débito.

Sinais de alerta

  • O handler aceita corpos sem assinatura «por agora»
  • Sem janela de replay, ou uma medida em semanas
  • Sobrescrita de estado sem comparar carimbos
  • Efeitos CRM/e-mail antes do ACK
  • Segredo de produção no chat
  • IDs de evento duplicados no mês passado sem ninguém a olhar
  • Erros ao cliente que despejam códigos crus de upstream

Comece com a IOSOR

Abra o seu console do IOSOR e inspecione as configuracoes ativas do seu ponto de extremidade de webhooks para recibos de entrega de entrada e retornos de eventos. Defina uma janela restrita de verificacao de repeticao de assinatura de cinco minutos e vincule o seu manipulador estritamente ao identificador de evento da plataforma.

Conclusão IOSOR

Manipuladores de webhooks nao verificados e a ausencia de janelas de repeticao transformam tentativas rotineiras de rede em vulnerabilidades de seguranca e alteracoes de estado duplicadas. Limitar a validade da assinatura por registro de horario e impor estrita idempotencia garante que tentativas automatizadas de entrega permanecidas as duas da manha continuem totalmente previsiveis.

Este guia foi útil?

Guias relacionados