Saltearse al contenido

Verificar firmas de webhooks con HMAC

La cabecera X-Signature de un webhook de Chaingateway permite comprobar que una solicitud procede realmente de Chaingateway. Contiene el HMAC-SHA256 del id de transacción (txid) del payload, calculado con su secreto personal y codificado en base64. Su receptor recalcula el valor y lo compara con la cabecera. La cabecera se envía una vez fijado un secreto personal.

Comprobación de la firma: Chaingateway calcula el HMAC-SHA256 del txid con su secreto personal y lo envía en X-Signature, y su receptor recalcula el valor y lo compara en tiempo constante Chaingateway firma base64( HMAC-SHA256( personal_secret, txid ) ) POST a su receptor cuerpo JSON con txid, cabecera X-Signature El receptor recalcula el HMAC mismo secreto, mismo txid Comparación en tiempo constante iguales: aceptar, distintos: rechazar con unestado de error
Solo se firma el txid. Los demás campos del payload no forman parte de la firma.

¿Contra qué protege la cabecera X-Signature?

Sección titulada «¿Contra qué protege la cabecera X-Signature?»

Protege contra solicitudes falsificadas: cualquiera puede enviar una solicitud POST a la URL pública de su receptor, pero solo un emisor que conozca el secreto personal puede generar una firma válida. HMAC, definido en la RFC 2104, combina una función hash con una clave secreta, aquí SHA-256. NIST FIPS 198-1 especifica la misma construcción como Keyed-Hash Message Authentication Code.

La firma cubre el txid y nada más. El importe, las direcciones y los campos del token del cuerpo no están firmados. Por eso un par válido de txid y firma no demuestra que el resto del cuerpo no haya cambiado. Tras la comprobación, trate el txid como clave de búsqueda: lea la transacción con GET /api/v2/{chain}/transactions/{txid} y acredite el pago con los datos que devuelve la API, no con el importe del cuerpo de la notificación.

Puede configurar o regenerar el secreto personal en los ajustes de su perfil. Siga estos pasos:

  1. Abra la configuración del perfil.
  2. Localice la sección etiquetada como «Personal Secret».
  3. Si no hay ningún secreto, haga clic en «Set Personal Secret» para generar uno. Si ya existe uno, haga clic en «Regenerate Secret» para sustituirlo.

Dos detalles importan en un sistema en producción. Si todavía no tiene un secreto personal, añadir uno activa la cabecera X-Signature en todos los webhooks salientes. Despliegue un receptor que acepte y verifique la cabecera antes de hacerlo. Si regenera un secreto existente, el nuevo secreto se aplica de inmediato a las notificaciones de webhook. Actualice el receptor al mismo tiempo, o rechazará solicitudes válidas.

¿Cómo se construye la cabecera X-Signature?

Sección titulada «¿Cómo se construye la cabecera X-Signature?»

Chaingateway lee el txid del payload, calcula sobre él un HMAC con la función hash SHA-256 usando el secreto personal como clave, y codifica en base64 los 32 bytes del resultado. El txid es el identificador único de la transacción que ya aparece en el cuerpo del webhook, así que el receptor tiene todo lo necesario para recalcular el valor. El secreto solo lo comparten Chaingateway y usted.

Recalcule el HMAC a partir del txid del cuerpo y compárelo con el valor de la cabecera. Use una función de comparación en tiempo constante, para que el tiempo de la comparación no revele nada del valor esperado. Los ejemplos siguientes lo hacen en Python, Java, PHP y JavaScript.

import hmac
import hashlib
import base64
def verify_signature(txid, received_signature, personal_secret):
# Generate the expected signature
expected_signature = base64.b64encode(hmac.new(
personal_secret.encode(),
txid.encode(),
hashlib.sha256
).digest()).decode()
# Compare the expected signature with the received signature
return hmac.compare_digest(expected_signature, received_signature)
# Example usage
txid = 'your_txid_here'
received_signature = 'received_signature_here'
personal_secret = 'your_personal_secret_here'
if verify_signature(txid, received_signature, personal_secret):
print("Signature is valid.")
else:
print("Invalid signature.")

¿Cómo puedo probar mi código de verificación?

Sección titulada «¿Cómo puedo probar mi código de verificación?»

Pruebe la función con una entrada fija antes de conectarla al tráfico real. Los valores siguientes son un vector de prueba que puede reproducir con cualquier herramienta HMAC-SHA256. El secreto es un marcador de posición, no un secreto personal real. Si su función devuelve otro valor para esta entrada, el error está en su código y no en el webhook.

personal_secret: my_personal_secret
txid: 18f52f2a55b94a6e3705de4abb18e95dfce79970f27b29450705c561e12b6988
X-Signature: t2vU2mYBCv/UvpKprNJB7qbgrCpPXKb6NWgL77xsZgQ=

Los errores habituales son calcular el hash de todo el cuerpo JSON en lugar del txid, usar el digest hexadecimal en lugar de base64 y comparar con ==, que no es en tiempo constante. Recuerde también que el secreto personal vale para toda la cuenta. Un secreto que regenere en los ajustes del perfil cambia a la vez la firma de todos los webhooks de la cuenta.

¿Qué debo hacer cuando la firma no coincide?

Sección titulada «¿Qué debo hacer cuando la firma no coincide?»

Rechace la solicitud con un estado de error como 401 o 403 y no procese el cuerpo. Registre el txid, la cabecera recibida y la dirección de origen, para distinguir un secreto mal configurado de una solicitud falsificada. Si el mismo emisor produce discrepancias justo después de regenerar el secreto, el receptor sigue usando el antiguo. Una solicitud falsificada que solo adivina un txid no puede producir una firma válida sin el secreto.

¿Qué más debe hacer un receptor de webhooks?

Sección titulada «¿Qué más debe hacer un receptor de webhooks?»

La verificación de la firma es una capa. Las medidas siguientes cubren el resto del recorrido.

  • Sirva el receptor por HTTPS, para que el payload viaje cifrado. La REST Security Cheat Sheet de OWASP recomienda HTTPS para todo endpoint que maneje datos sensibles.
  • Rechace con un estado de error las solicitudes con un X-Signature ausente o incorrecto, y regístrelas.
  • Use el txid como clave de idempotencia. Una notificación que reenvía con POST /api/v2/{chain}/webhooks/notifications/{id}/retry lleva el mismo txid y no debe acreditar un pago dos veces.
  • Guarde el secreto personal en un almacén de secretos, nunca en el repositorio, y rótelo si pudo filtrarse. Chaingateway no reintenta por sí mismo las entregas fallidas, así que planifique la actualización del receptor y del secreto como un solo paso, y reenvíe después las notificaciones perdidas desde la lista de fallidas.