¿Qué es un Webhook?
Los webhooks son una forma ingeniosa de que las aplicaciones intercambien información en tiempo real siempre que ocurran eventos específicos, todo sin la necesidad de sondeos constantes. Funcionan como un puente pasivo entre dos sistemas, comunicándose a través de solicitudes HTTP POST. Una vez que hayas configurado los webhooks de OnePay, recibirás notificaciones de eventos a tiempo para cada actividad o función generada dentro del flujo de OnePay.
¿Por qué elegir Webhooks?
Los webhooks son altamente recomendados para mantener tu sistema sincronizado con el progreso de los pagos y las actualizaciones de estado. Gracias a las notificaciones automáticas de eventos, tu sistema puede evitar la sobrecarga de solicitudes frecuentes a OnePay. En su lugar, podrás procesar la información de pago precisamente cuando la necesites.
Lo que necesitas saber antes de comenzar
Antes de sumergirte en los webhooks de OnePay, hay algunos requisitos previos:
Crea una API REST Pública: Necesitarás establecer una API REST pública capaz de recibir notificaciones de eventos a través de solicitudes POST. Es importante que esta API REST requiera autenticación o imponga restricciones de acceso a través de encabezados.
Comunicación Segura: Aunque estés utilizando una API pública, ten la seguridad de que tu comunicación con las notificaciones de eventos de OnePay permanecerá segura. Estas notificaciones no serán accesibles al público y solo se comunicarán con tu API REST a través de una URL única.
Siguiendo estos pasos, puedes integrar sin problemas los webhooks de OnePay en tu sistema para actualizaciones en tiempo real sin el problema de solicitudes constantes.
Firmando webhooks
Durante el proceso de configuración, es habitual crear, almacenar de forma segura e intercambiar una clave confidencial entre tu aplicación y la aplicación receptora, que está destinada a recibir webhooks. OnePay utiliza esta clave secreta para autenticar las llamadas de webhook.
Por defecto, OnePay incorpora un encabezado de "firma" dentro de la solicitud, que contiene una firma única. Esta firma permite que la aplicación receptora verifique la integridad de la carga útil, asegurando que permanezca sin alterar durante el tránsito.
Aquí está el método mediante el cual se calcula esta firma:
secret = 'wh_tok_BzgFuoj36cyuN0QAMtcTFVgIlU7doHZCugHalwq1non79lVrP3qV'
hmac('sha256', json, secret)
HMAC
HMAC es un MAC/hash con clave, no un cifrado. No está diseñado para ser descifrado. Si quieres cifrar algo, usa un cifrado, como AES, preferiblemente en un modo autenticado como AES-GCM.
Incluso conociendo la clave, la única forma de "descifrar" es adivinando toda la entrada y luego comparando la salida.
Encabezado de Autenticación para Webhooks
En cada solicitud, recibirás un encabezado de autenticación que contiene un token de autorización. Es importante destacar que este token es distinto de la clave secreta. Este encabezado también se puede utilizar para verificar el origen de la información transmitida.
x-webhook-token: 'wh_hdr_uqviEXJhuh59KfoQW9qwNMmH8A4vJZkCDDkskHBcknfvmTejImqr'
Configuración de tokens en la plataforma
Puedes configurar los webhooks directamente en el administrador en la siguiente URL: Admin
Testing
Para un desarrollo más extenso en el entorno local, recomendamos altamente utilizar urls de ngrok.com.