Webhooks para obtener actualizaciones en tiempo real

Hola Cash usa Webhooks para notificarte. Estos se entregan como cargas JSON a través de HTTPS. Puedes usar estas notificaciones para reaccionar a diferentes eventos y ejecutar acciones en tu app. Por ejemplo, cuando recibes un webhook por el pago de un pedido y reaccionas enviando un mensaje a su almacén para su envío.

¿Cómo recibir webhooks de Hola Cash?

  1. Inicia sesión en el Cash Portal con tus credenciales.
  2. Navega hacia el menú de Desarrollador
  3. Después crea un webhook como un endpoint HTTPS (URL).
  4. Webhook # 1
  5. El nuevo webhook aparecerá en la lista de Webhooks, puedes editarlo en cualquier momento o crear nuevos URLs para webhooks.
  6. Webhook # 1
  7. Usa el Webhook Key para validar los webhooks provenientes de Hola Cash. Este es un paso muy importante ya que podrás saber si el evento viene de Hola Cash y no de un tercero malicioso.

¿Cómo validar un webhook de Hola Cash?

Secuencias de reintentos

Los webhooks de Hola Cash tienen métodos de reintento integrados para los codigos de status de respuesta 3xx, 4xx, 5xx. Hola Cash siempre espera respuestas 2xx.


Los webhooks que recibas de nosotros contendrán el encabezado HOLACASH-SIGN, que es una cadena separada por una coma. Ve ejemplo a continuación:

1648551779.84847,EB9A452AFCBA258FF718033A6964336B7C8AC4318E5533DDEFCC3BB99FEDA079

La primera mitad del valor es una marca de tiempo que representa cuándo se envió el webhook. La segunda parte es una representación hexadecimal de un hash HMAC-SHA256.


Debes verificar este hash por tu parte para asegurarte de que se está procesando un webhook generado por Hola Cash, para lo cual necesitarás tu clave de webhook. Dado que la clave del webhook es un secreto compartido, debe almacenarse de forma segura.


El algoritmo para verificar la firma es:

  1. Recupera el encabezado http HOLACASH-SIGN.
  2. Asumamos que almacenas la marca de tiempo en una variable llamada timestamp.
  3. Separa los valores y almacenalos en variables distintas
  4. Recupera el cuerpo http. Verifica que sea un JSON válido.
  5. Almacena el JSON como una cadena de caracteres sin espacio. Recomendamos, por ejemplo, en JavaScript usar stringify para convertir correctamente JSON en una cadena de caracteres. O en Python podrías utilizar:
  6. json.dumps(payload, separators=(',',';'))

    {

    "event_type":"charge.succeeded",

    "payload": {

    "id": "935e0646-a0de-4acf-9954-542b2a97e5f9",

    "status_details": {

    "status": "success",

    "message": "charge created",

    "date_created": 1648551779704,

    "detail": {

    "code": null,

    "message": null,

    "additional_details": [

    {

    "name": "card_brand",

    "data": "visa"

    },

    {

    "name": "card_type",

    "data": "credit"

    },

    {

    "name": "card_bin",

    "data": "424242"

    },

    {

    "name": "card_last_four_digits",

    "data": "4242"

    },

    {

    "name": "currency_code",

    "data": "MXN"

    },

    {

    "name": "expiration_year",

    "data": "23"

    },

    {

    "name": "expiration_month",

    "data": "12"

    },

    {

    "name": "charge_status",

    "data": "captured"

    }

    ]

    }

    },

    },

    "charge": {

    "description": "testing",

    "amount_details": {

    "amount": 4500,

    "currency_code": "MXN"

    },

    "payment_detail": {

    "credentials": {

    "payment_method": {

    "method": "credit_or_debit_card",

    "display_name": null,

    "logo": null

    },

    "holacash_payment_token": null,

    "credit_or_debit_card": {

    "card_number": "424242XXXXXX4242",

    "expiration_month": "12",

    "expiration_year": "2023",

    "card_validation_code": "XXX"

    },

    "pay_by_store_type": null

    },

    "address": null,

    "contact": null,

    "name": null

    },

    "processing_instructions": {

    "auto_capture": true

    },

    "purchase_details": {

    "external_system_order_id": null,

    "holacash_system_order_id": "a85610ac-4eab-444d-97d8-4e610011be5e",

    "holacash_system_order_id": "a85610ac-4eab-444d-97d8-4e610011be5e",

    "order_data": null

    },

    "consumer_details": {

    "external_consumer_id": null,

    "address": null,

    "contact": {

    "phone_1": "13212312412",

    "email": "asdasd@holacash.mx",

    "additional_contact_info": null

    },

    "name": {

    "first_name": "asdasd",

    "second_first_name": null,

    "first_last_name": null,

    "second_last_name": null

    }

    },

    "shipping_details": null,

    "additional_details": null

    },

    "related_transactions": null,

    "additional_detail": null

    }

    }

  7. Concatena al timestamp un punto (“.”) y el payload de cadena.
  8. stringToSign = timestamp + "." + json_as_string

  9. Utiliza tu clave de webhook para firmar la cadena concatenada con un algoritmo HMAC-SHA256.
  10. Compara la firma obtenida con la que recibiste en el encabezado HOLCASH-SIGN. Usa una biblioteca criptográfica para comparar los hashes. Evita la comparación de cadenas.

El resultado esperado de la comparación es que ambas firmas sean idénticas. Cualquier solicitud con una firma no válida debe descartarse.

Ejemplos de código para validación de firmas

Puedes consultar las validaciones de firma de muestra aquí, en la carpeta de tu lenguaje preferido con el nombre de archivo webhook_signature