HMAC en Python: Valida Firmas de Webhooks

HMAC combina un secreto compartido con una función hash para autenticar un mensaje. En webhooks, el proveedor firma los bytes enviados y tu aplicación calcula el valor esperado antes de confiar en el evento.

import hashlib
import hmac

def assinatura_valida(corpo: bytes, recebida: str, segredo: bytes) -> bool:
    esperada = hmac.new(segredo, corpo, hashlib.sha256).hexdigest()
    return hmac.compare_digest(esperada, recebida)

payload = b'{"evento":"pedido.criado"}'
print(assinatura_valida(payload, "digest-recebido", b"segredo"))

Usa exactamente el algoritmo y formato del proveedor, que puede incluir prefijo o timestamp en el mensaje firmado. Lee el cuerpo bruto antes del parsing y carga el secreto desde configuración protegida. Nunca registres el secreto ni el header completo.

Buenas prácticas

Compara con hmac.compare_digest() para reducir filtraciones temporales. Rechaza firmas ausentes o mal formadas antes de procesar. Mitiga replay con una ventana temporal y almacenando IDs consumidos. Rota secretos con un solapamiento controlado que acepte temporalmente la clave anterior.

Comprende el digest en hashlib e integridad de archivos. La guía de seguridad de APIs cubre autorización, límites y logs.

La documentación oficial de hmac, consultada el 22 de julio de 2026, detalla la API y sus límites.