- 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:- 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
- Inclusión en el encabezado: la firma se incluye en el encabezado HTTP
x-hmac-signature - Verificación: tu servidor extrae la firma del encabezado, la recrea con el mismo payload y la misma clave secreta, y luego las compara
- 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 definehmac_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 adicionalx-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 encabezadox-hmac-signature agregado junto a los demás encabezados de autenticación configurados.
Ejemplo de código de verificación
Verifica el encabezadox-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:
x-hmac-signature: