Segurança de webhooks: assinatura, replay e validação de origem

Um endpoint de webhook é uma porta pública para eventos do seu sistema. Por isso, ele precisa assumir que qualquer pessoa na internet pode tentar chamá-lo. A segurança não deve depender de uma URL “difícil de adivinhar”.

Em pagamentos, um webhook mal validado pode causar atualização indevida de pedidos, créditos duplicados ou estados inconsistentes. O objetivo é garantir autenticidade, integridade e processamento idempotente.

Comece por HTTPS

Webhooks devem trafegar por HTTPS. Isso protege o conteúdo em trânsito e reduz risco de interceptação. Certificado válido é requisito básico, não uma camada suficiente por si só.

Valide a assinatura quando o provedor oferecer

Muitos provedores assinam o payload usando um segredo compartilhado. O servidor receptor recalcula a assinatura e compara com a enviada no cabeçalho.

Dois cuidados são essenciais:

• usar exatamente o algoritmo e a construção definidos pelo provedor;
• validar usando o corpo bruto da requisição quando a documentação exigir, antes de reserializar o JSON.

Alterar espaços, ordem de campos ou codificação antes da validação pode fazer uma assinatura correta parecer inválida.

Proteja contra replay

Mesmo um evento assinado pode ser capturado e reenviado. Quando o protocolo do provedor inclui timestamp ou nonce, valide a janela de tempo e rejeite mensagens antigas fora do limite esperado.

Além disso, registre um identificador único do evento. Se o mesmo evento chegar novamente, a aplicação deve reconhecê-lo e evitar processamento duplicado.

Idempotência é parte da segurança operacional

Deduplicar o evento não é suficiente se a lógica de negócio puder ser executada duas vezes por caminhos diferentes. A ação final também deve ser idempotente.

Exemplo: “liberar pedido 123” precisa verificar se o pedido já foi liberado para aquela transação antes de criar estoque, crédito, comissão ou notificação novamente.

Veja webhook de pagamento: como funciona e idempotência em APIs de pagamento.

IP allowlist ajuda, mas não deve ser a única defesa

Quando o provedor publica faixas de IP oficiais e estáveis, uma allowlist pode reduzir superfície de ataque. Mas endereços podem mudar, proxies podem existir e algumas integrações não oferecem essa garantia.

Trate IP como camada adicional. A validação criptográfica do evento é mais adequada quando disponível.

Rotação de segredo

Segredos de webhook não devem ficar eternamente ativos. Uma estratégia madura permite rotação sem indisponibilidade:

1. gerar novo segredo;
2. aceitar temporariamente segredo novo e antigo;
3. atualizar o remetente;
4. monitorar erros de assinatura;
5. revogar o segredo anterior.

Nunca grave o segredo em log e evite colocá-lo diretamente no código-fonte.

Responda rápido

O endpoint deve validar, registrar e responder dentro de um tempo previsível. Processamentos pesados podem ser delegados a uma fila ou rotina posterior.

Quando a resposta demora, o remetente pode considerar a entrega falha e tentar novamente. Isso aumenta duplicidade e pressão sobre o sistema.

Rate limiting com cuidado

É possível limitar abuso, mas um limite agressivo pode bloquear picos legítimos de eventos. Em vez de um número arbitrário, observe o tráfego real e separe endpoints públicos comuns de rotas críticas de webhook.

Logs que você realmente precisa

• ID do evento;
• tipo do evento;
• ID da transação;
• timestamp de recebimento;
• resultado da validação de assinatura;
• status HTTP devolvido;
• tempo de processamento;
• número de tentativas.

Não registre tokens, segredos, credenciais completas ou dados sensíveis que não sejam necessários para diagnóstico.

O que fazer quando a validação falhar

Não processe o evento. Retorne o status apropriado à integração, registre o motivo com segurança e gere alerta se a taxa de falha fugir do padrão.

Uma falha isolada pode ser configuração. Uma sequência de falhas pode indicar rotação incompleta, mudança de formato, relógio fora de sincronia ou tentativa maliciosa.

Checklist de produção

• HTTPS obrigatório;
• assinatura validada conforme documentação;
• corpo bruto preservado quando necessário;
• timestamp/nonce verificados quando disponíveis;
• ID de evento deduplicado;
• lógica de negócio idempotente;
• segredo fora do repositório;
• rotação planejada;
• logs sem dados sensíveis;
• alerta para falhas anormais;
• reconciliação periódica como rede de segurança.

Resumo

Segurança de webhook não é um único cabeçalho. É uma combinação de transporte seguro, assinatura, replay protection, idempotência, segredo bem gerenciado e monitoramento.

Para conhecer a proposta da GetKryon, acesse getkryon.com.