Verificación de firmas de webhooks de Stripe: Stripe-Signature, tolerancia de marca de tiempo y rotación de secretos

Qué es

La guía de webhooks de Stripe documenta el encabezado Stripe-Signature y la función auxiliar de verificación constructEvent(), que recibe el cuerpo sin procesar de la solicitud, el valor del encabezado y el secreto del endpoint (con el prefijo whsec_). El encabezado contiene una marca de tiempo t= y una o varias firmas, cada una precedida por un esquema; según la documentación, "currently, the only valid live signature scheme is v1" (actualmente el único esquema válido en producción), y los eventos de prueba incluyen además una firma falsa v0 que debe ignorarse. Como la marca de tiempo "is part of the signed payload, it's also verified by the signature" (forma parte de los datos firmados y, por tanto, la firma también la verifica), y "our libraries have a default tolerance of 5 minutes between the timestamp and the current time." (las bibliotecas admiten por defecto una diferencia de 5 minutos con la hora actual). La cadena firmada se compone de la marca de tiempo, un . y el cuerpo sin procesar; la clave HMAC es el secreto del endpoint tal como aparece, incluido el prefijo whsec_. La página de solución de problemas de Stripe muestra el mensaje de error: Webhook signature verification failed. Err: No signatures found matching the expected signature for payload.

Por qué importa

La ventana de tolerancia impide reenviar (ataque de repetición) una carga útil válida que haya sido interceptada. La página de solución de problemas de Stripe señala como causa más frecuente del error anterior el uso de un secreto de endpoint equivocado (el secreto de stripe listen en la CLI y el secreto de un endpoint del Dashboard empiezan ambos por whsec_, pero son distintos); la siguiente causa es un cuerpo modificado (véase el artículo sobre la trampa del cuerpo sin procesar), ya que cualquier framework que reformatee el JSON antes de que llegue a su manejador altera los bytes que firmó Stripe. Cuando se rota un secreto y se pospone la caducidad del anterior (hasta 24 horas), "Stripe generates one signature per secret until expiration" (Stripe genera una firma por secreto hasta la caducidad), de modo que el encabezado contiene temporalmente más de un valor v1=; el receptor debe aceptar la solicitud si coincide con cualquiera de ellos.

Cómo aplicarlo

• Lea el cuerpo sin procesar, sin parsear, en la ruta del webhook.
• Divida Stripe-Signature por comas, tome t= como marca de tiempo y recopile todos los valores v1=.
• Vuelva a calcular el HMAC-SHA256 de "{t}.{raw_body}" con el secreto del endpoint y compárelo con cada valor v1 mediante una función de tiempo constante; acepte si hay alguna coincidencia.
• Rechace la solicitud si la marca de tiempo supera la tolerancia (300 segundos, salvo que se amplíe a propósito); sincronice el reloj con NTP en lugar de aumentar la tolerancia y nunca pase 0, que "disables the recency check entirely" (desactiva por completo la comprobación de antigüedad). El fragmento de código también rechaza marcas de tiempo futuras, lo que es más estricto que las bibliotecas.
• Durante una rotación con caducidad pospuesta, despliegue el nuevo secreto whsec_ antes de que caduque el anterior; mientras ambos estén activos, cualquiera de los dos genera una coincidencia.

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)

Trampas

Registrar un express.json() global para toda la aplicación antes de la ruta del webhook; la página de solución de problemas de Stripe indica que app.use(express.json()) debe ir después de ella. Aumentar la tolerancia en lugar de corregir el desfase del reloj. Parsear el encabezado en un diccionario, que conserva un único valor v1 y rechaza entregas válidas durante una rotación. Decodificar el secreto en Base64 como hace Standard Webhooks; las bibliotecas de Stripe usan la cadena completa como clave.