Verificar firmas de webhooks (HMAC)

La verificación de la firma de los webhooks mediante HMAC (Código de Autenticación de Mensajes basado en Hash) garantiza que los webhooks enviados a tu servidor proceden realmente de Yuno y no han sido interceptados o modificados durante la transmisión. Esto añade una capa adicional de seguridad más allá de los métodos de autenticación como OAuth.

Mientras que OAuth proporciona autenticación (verificando quién envía el pedido), las firmas HMAC proporcionan:

Integridad de los datos: Confirma que la carga útil del webhook no ha sido manipulada
Autenticidad: Verifica que el webhook procede realmente de Yuno
Protección: Protección contra ataques de intermediario y ataques de repetición
Conformidad: Cumple los requisitos de seguridad para el tratamiento de datos sensibles de pago

Cómo funcionan las firmas HMAC

Cuando Yuno envía un webhook a tu servidor:

Generación de firma: Yuno crea una firma HMAC haciendo un hash de la carga útil del webhook con la clave secreta de tu cliente utilizando el algoritmo SHA-256
Inclusión en la cabecera: La firma se incluye en el x-hmac-signature Cabecera HTTP
Verificación: Tu servidor extrae la firma de la cabecera, la recrea utilizando la misma carga útil y clave secreta, y luego compara
Validación: Si las firmas coinciden, el webhook es auténtico e inalterado

Configuración

Para activar la verificación de firma HMAC, marca Usar autenticación HMAC al crear o editar un webhook en el panel de control de Yuno.

Consulta Configurar webhooks para obtener instrucciones paso a paso sobre cómo acceder al panel de configuración de webhooks.

Qué cambia con HMAC

Cuando está activada la verificación de firma HMAC, los webhooks de Yuno incluyen un elemento adicional x-hmac-signature cabecera HTTP. La carga útil JSON del webhook no cambia.

Ejemplo de webhook pedido con HMAC

POST /your-webhook-endpoint HTTP/1.1
Host: your-server.com
Content-Type: application/json
x-api-key: your-api-key
x-secret: your-secret
x-hmac-signature: K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=

{
  "type": "payment",
  "type_event": "payment.purchase",
  "account_id": "2c05976d-1234-1234-1234-6421883de48d",
  "retry": 0,
  "version": 2,
  "data": {
    "payment": {
      "id": "a546c566-1703-4fba-b334-c46e89bc97f7",
      "status": "SUCCEEDED"
    }
  }
}

Cómo funcionan las firmas HMAC

Configuración

Qué cambia con HMAC

Ejemplo de webhook pedido con HMAC

Documentación relacionada