Administración de Webhooks

Integración con webhooks de pagos

Esta integración te permite recibir notificaciones de transacciones (pagos, devoluciones o anulaciones) en un formato específico mediante una solicitud POST.

Para suscribirte a este evento, sigue estos pasos:

  1. Configura tu aplicación para recibir notificaciones de webhooks en una URL pública y segura con el formato esperado que se muestra a continuación.
  2. Crea una suscripción a webhooks para comenzar a recibir las notificaciones.
  3. Asegurate de validar los webhooks entrantes utilizando el token correspondiente para verificar su origen Menta y garantizar que no han sido manipulados.

Ejemplo de notificación:

{
  "notification_type": "OPERATION_CREATED",
  "merchant_id": "db3ae307-4a5c-4cbb-b48c-80bf1a3fde1d",
  "user": "[email protected]",
  "datetime": "2022-12-31T23:23:23Z",
  "detail": {
    "terminal_id": "72171704-7806-4347-b08b-bc2d2d96e68e",
    "operation_id": "2fce7d49-f3e2-4b1f-a7bb-7f16d3ea64a2",
    "ticket_id": "111111111",
    "operation_type": "PAYMENT",
    "qr_id": null,
    "operation_status": "APPROVED",
    "currency": "ARS",
    "operation_amount": "200000",
    "operation_additional_info": "ABC1234",
    "payment_method_type": "DEBIT",
    "payment_method_detail": "VISA"
  }
}

Validación de los webhooks

Para garantizar que su servidor solo procese entregas de webhooks enviadas por Menta y para asegurarse de que la entrega no haya sido manipulada, es fundamental validar la firma del webhook antes de continuar con el procesamiento.

Menta utiliza la secret key proporcionada durante la suscripción para generar un hash de firma distinto en cada solicitud, la cual se envía como valor del encabezado X-Menta-Signature-V1 en cada webhook. Para verificar que la firma es auténtica, el cliente debe aplicar la misma función de hash (HMAC con SHA-256) junto con la secret key, y asegurarse de que coincida con la firma enviada.

Pasos para generar y validar firma

  1. Concatenar los siguientes elementos:
TimestampEl punto "."El cuerpo (payload) de la solicitud.
enviado en el encabezado X-Menta-Signature-Timestamp.en formato JSON as String
  1. Obtener la secret key guardada en su servidor.
  2. Aplicar la función de hash HMAC con algoritmo SHA-256 junto con la secret key.
  3. Comparar la firma generada con la firma enviada en el encabezado X-Menta-Signature-V1.

Ejemplo de implementación en Kotlin

Puede utilizar el lenguaje de programación que prefiera para implementar la verificación HMAC en su código.

import java.util.Formatter
import javax.crypto.Mac
import javax.crypto.spec.SecretKeySpec
 
class HashProvider {
 
  fun generateHMAC(timestamp: String, body: String, secretKey: String): String {
    val msg = "$timestamp.$body"
    val signingKey = SecretKeySpec(secretKey.toByteArray(), "HmacSHA256")
    val mac = Mac.getInstance("HmacSHA256")
    mac.init(signingKey)         
    val bytes = mac.doFinal(msg.toByteArray())
    return format(bytes)
  }
    
  private fun format(bytes: ByteArray): String {
    val formatter = Formatter()
    bytes.forEach { formatter.format("%02x", it) }
    return formatter.toString()
  } 
}

Probando validación

Para probar la validación de webhooks, puede utilizar los siguientes valores de secret key, timestamp y JSON payload:

secret keytimestamp
secretKey!1697657734

Payload:

{"notification_type":"OPERATION_CREATED","merchant_id":"c2192cf8-e221-4ccc-83d4-1c2105d46b9a","user":"[email protected]","datetime":"2023-07-23T21:10Z","detail":{"terminal_id":"39b4500d-8e14-45ae-89e2-63135534132b","operation_id":"8e02915b-9387-412c-946a-bf9c046f62ff","ticket_id":"50691299","operation_type":"PAYMENT","qr_id":null,"operation_status":"APPROVED","currency":"ARS","operation_amount":"100","operation_additional_info":"","payment_method_type":"DEBIT","payment_method_detail":"MASTERCARD"}}

Si su implementación es correcta, las firmas que genere deben coincidir con los siguientes valores de firma:

el resultado de la firma y el header X-Menta-Signature-V1: 58f8e39497b01f53d13c5144fcd74ddc3bb33aee35d99cd4989b5e04bdf216f7

Recomendaciones

  1. Valide el timestamp incluido en la solicitud para evitar ataques de repetición (replay-attack). Un ataque de repetición ocurre cuando un atacante intercepta una solicitud válida junto con su firma y la retransmite. El timestamp se incluye en el proceso de hash y es verificado por la firma, por lo que un atacante no puede cambiar el timestamp sin invalidar la firma. Si la firma es válida pero el timestamp es demasiado antiguo, se recomienda rechazar la solicitud.

  2. Asegúrese de que el payload y los encabezados no se modifiquen antes de la verificación. Si utiliza un proxy o un equilibrador de carga, asegúrese de que estos componentes no modifiquen el payload ni los encabezados.

  3. Si su lenguaje de programación y la implementación del servidor especifican una codificación de caracteres, asegúrese de manejar el payload como UTF-8. Y ademas, se encuentren en Formato JSON antes de generar el hash.