Saltar al contenido principal
La verificación de firmas de webhooks mediante HMAC (Hash-based Message Authentication Code) garantiza que los webhooks enviados a tu servidor realmente provienen de Yuno y no han sido interceptados ni modificados durante la transmisión. Esto agrega una capa extra de seguridad más allá de métodos de autenticación como OAuth. Mientras que OAuth proporciona autenticación (verifica quién envía la solicitud), las firmas HMAC ofrecen:
  • Integridad de los datos: confirma que el payload del webhook no ha sido alterado
  • Autenticidad: verifica que el webhook realmente proviene de Yuno
  • Protección: protege contra ataques de intermediario (man-in-the-middle) y ataques de repetición
  • Cumplimiento: ayuda a cumplir los requisitos de PCI DSS para el manejo de datos sensibles de pago

Cómo funcionan las firmas HMAC

Cuando Yuno envía un webhook a tu servidor:
  1. Generación de la firma: Yuno crea una firma HMAC aplicando un hash al payload del webhook con la clave secreta de tu cliente, usando el algoritmo SHA-256
  2. Inclusión en el encabezado: la firma se incluye en el encabezado HTTP x-hmac-signature
  3. Verificación: tu servidor extrae la firma del encabezado, la recrea con el mismo payload y la misma clave secreta, y luego las compara
  4. Validación: si las firmas coinciden, el webhook es auténtico y no fue alterado

Configuración

Para habilitar la verificación de firmas HMAC, marca Use HMAC Authentication al crear o editar un webhook en el Dashboard de Yuno, o define hmac_client_secret mediante la API de Webhooks. La verificación funciona igual con cualquiera de las dos formas. Consulta Configurar webhooks para ver las instrucciones paso a paso de ambas.

Qué cambia con HMAC

Cuando la verificación de firmas HMAC está habilitada, los webhooks de Yuno incluyen un encabezado HTTP adicional x-hmac-signature. El payload JSON del webhook no cambia.

Ejemplo de solicitud de webhook con HMAC

Así se ve una solicitud de webhook con el encabezado x-hmac-signature agregado junto a los demás encabezados de autenticación configurados.

Ejemplo de código de verificación

Verifica el encabezado x-hmac-signature usando el cuerpo sin procesar de la solicitud (antes de interpretar el JSON) y el mismo secreto configurado para el webhook en el Dashboard de Yuno. No vuelvas a serializar el JSON primero. Un cambio en el orden de las claves o en los espacios en blanco produce una firma distinta a la que envió Yuno. Node.js (Express): usa un body parser que conserve el cuerpo sin procesar en la ruta del webhook (por ejemplo, express.raw() para esa ruta) y luego:
Python: usa los bytes del cuerpo sin procesar de la solicitud y el encabezado x-hmac-signature:
Si la firma calculada no coincide con el encabezado, rechaza el webhook (por ejemplo, devuelve 401).