Verificação de assinaturas de webhook do Stripe: Stripe-Signature, tolerância de timestamp e rotação de segredo

O que é

O guia de webhooks do Stripe documenta o cabeçalho Stripe-Signature e o helper de verificação constructEvent(), que recebe o corpo bruto da requisição, o valor do cabeçalho e o segredo do endpoint (com prefixo whsec_). O cabeçalho traz um timestamp t= e uma ou mais assinaturas, cada uma precedida pelo nome do esquema. A documentação afirma: "currently, the only valid live signature scheme is v1". Os eventos de teste também trazem uma assinatura falsa v0, que deve ser ignorada. O timestamp faz parte do payload assinado e, por isso, também é validado pela assinatura ("is part of the signed payload, it's also verified by the signature"); além disso, "our libraries have a default tolerance of 5 minutes between the timestamp and the current time." A string assinada é formada pelo timestamp, um . e o corpo bruto; a chave do HMAC é o segredo do endpoint exatamente como exibido, incluindo o prefixo whsec_. A página de solução de problemas do Stripe mostra a mensagem de falha: Webhook signature verification failed. Err: No signatures found matching the expected signature for payload.

Por que importa

A janela de tolerância impede o replay de um payload válido que tenha sido capturado. A página de solução de problemas do Stripe aponta o segredo de endpoint errado como a causa mais comum da falha acima (o segredo da CLI em stripe listen e o segredo de um endpoint no Dashboard começam ambos com whsec_, mas são diferentes). A causa seguinte é um corpo modificado (veja o artigo sobre a armadilha do corpo bruto): qualquer framework que reformate o JSON antes de ele chegar ao seu handler altera os bytes que o Stripe assinou. Ao substituir um segredo e adiar a expiração do antigo (por até 24 horas), "Stripe generates one signature per secret until expiration"; assim, o cabeçalho passa a conter temporariamente mais de um valor v1=, e o receptor deve aceitar a correspondência com qualquer um deles.

Como aplicar

• Leia o corpo bruto, sem parsing, na rota do webhook.
• Divida Stripe-Signature por vírgulas, leia t= como timestamp e colete todos os valores v1=.
• Recalcule o HMAC-SHA256 de "{t}.{raw_body}" com o segredo do endpoint e compare com cada valor v1 usando uma função de tempo constante; aceite se houver qualquer correspondência.
• Rejeite se o timestamp for mais antigo que a tolerância (300 segundos, a menos que seja ampliada de propósito); sincronize o relógio via NTP em vez de aumentar a tolerância e nunca passe 0, que "disables the recency check entirely". O trecho abaixo também rejeita timestamps no futuro, o que é mais estrito do que as bibliotecas.
• Durante uma rotação com expiração adiada, publique o novo segredo whsec_ antes de o antigo expirar; enquanto ambos estiverem ativos, qualquer um dos dois confere.

import hmac, hashlib, time

def verify_stripe(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
    ts, sigs = None, []
    for item in header.split(","):
        key, _, value = item.strip().partition("=")
        if key == "t" and value.isdecimal():
            ts = value
        elif key == "v1":                        # ignore v0 and unknown schemes
            sigs.append(value.encode())
    if ts is None or not sigs or abs(time.time() - int(ts)) > tolerance:
        return False
    signed = ts.encode() + b"." + raw_body       # exact bytes Stripe signed
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest().encode()
    return any(hmac.compare_digest(expected, s) for s in sigs)

Armadilhas

Montar um express.json() global no app antes da rota do webhook; a página de solução de problemas do Stripe orienta colocar app.use(express.json()) depois dela. Aumentar a tolerância em vez de corrigir o desvio do relógio. Converter o cabeçalho em um dicionário, que guarda apenas um valor v1 e rejeita entregas válidas durante a rotação. Decodificar o segredo em Base64, como faz o Standard Webhooks; as bibliotecas do Stripe usam a string completa como chave.