Segurança de webhook Stripe

Por que o webhook é crítico

O webhook é onde o seu SaaS descobre que um pagamento aconteceu. Se ele aceita qualquer requisição, um atacante forja um evento e libera acesso pago sem pagar. Se ele processa o mesmo evento duas vezes, você entrega em dobro ou credita errado.

A boa notícia: as duas defesas centrais — assinatura e idempotência — são simples e resolvem a maior parte do risco.

Verificação de assinatura

Todo evento precisa ser validado com o segredo do endpoint antes de qualquer efeito. Use o corpo bruto (raw body) da requisição para conferir a assinatura; se o seu framework fizer parse do JSON antes, a verificação falha silenciosamente.

• Valide a assinatura com o signing secret do endpoint.
• Use o raw body, não o JSON já parseado.
• Rejeite evento sem assinatura válida com 400, sem efeito colateral.

Idempotência e ordem

Provedores reenviam eventos e não garantem ordem. Guarde o id do evento processado e ignore repetição. Trate o estado como convergente: o que importa é o estado final da assinatura, não a sequência exata de chegada.

• Grave o event id e ignore reprocessamento.
• Torne o handler idempotente: rodar duas vezes = mesmo resultado.
• Não assuma ordem; reconcilie pelo estado atual no provedor quando em dúvida.

Liberar acesso na hora certa

Libere o plano só depois da confirmação real do pagamento — especialmente em Pix, boleto e métodos assíncronos, onde o "sucesso" na tela não significa pago. A página de sucesso é UX; o webhook é a fonte de verdade.