Que un cliente complete un pago con criptomonedas es solo el comienzo del proceso. Tu sitio web o aplicación aún debe confirmar el resultado, actualizar el pedido correcto, avisar al cliente y decidir si puede comenzar la preparación o entrega. Los webhooks de OxaPay lo permiten enviando actualizaciones del estado del pago directamente a tu servidor.
Una integración fiable de webhooks hace mucho más que recibir una notificación. Comprueba la autenticidad de la devolución de llamada, la vincula al pago correcto, gestiona de forma segura las entregas repetidas y consulta el estado cuando la información se retrasa o resulta incierta. Esta guía explica todo el proceso de forma práctica para propietarios de negocios, equipos de producto y desarrolladores.
Qué hace un webhook de OxaPay
Un webhook es un mensaje de servidor a servidor que se activa ante un evento. En lugar de que tu sistema pregunte constantemente si ha cambiado un pago, OxaPay envía una devolución de llamada JSON a la URL HTTPS que indiques cuando haya nueva información disponible.
Tu aplicación puede utilizar la actualización verificada para cambiar el estado de un pedido, activar un servicio, enviar una confirmación o crear un registro para la conciliación. Esto resulta especialmente útil porque un pago con criptomonedas puede pasar por varios estados antes de alcanzar un resultado empresarial definitivo.
La página de retorno del navegador no debe considerarse una prueba de pago. El cliente puede cerrar la página, perder la conexión o visitar una URL de retorno sin que el pago haya alcanzado el estado necesario. La decisión de tramitar un pedido debe basarse en información de pago verificada en el servidor.
Cuándo necesita tu empresa un webhook de pagos
Un webhook personalizado aporta más valor cuando el resultado de un pago debe activar automáticamente otra acción. Algunos ejemplos habituales son:
- pasar un pedido de comercio electrónico de pendiente a listo para tramitar;
- activar una cuenta SaaS o ampliar una suscripción;
- enviar una confirmación de pago por correo electrónico, SMS o mensaje en la aplicación;
- actualizar el inventario, el CRM, la contabilidad o los sistemas internos de informes;
- avisar al equipo de operaciones cuando un pago sea insuficiente o haya caducado, o requiera revisión por otro motivo.
Si utilizas un complemento de pagocompatible, es posible que la integración ya gestione gran parte de esta lógica. Si solo creas Payment Links and review them manually, you may not need a custom endpoint. integraciones directas mediante API and custom platforms usually benefit the most.
Cómo funciona el flujo de webhooks de OxaPay
- Your system creates or identifies a payment and stores OxaPay’s
track_idwith your own order or customer reference. - El cliente envía el pago y su estado cambia mientras OxaPay lo procesa.
- OxaPay envía una devolución de llamada JSON firmada a la URL de callback configurada.
- Tu servidor verifica la firma antes de confiar en el mensaje.
- Tu servidor vincula el callback con el registro correcto y valida los datos importantes del pago.
- Tu aplicación registra el evento, ejecuta una sola vez cada acción empresarial autorizada y devuelve una respuesta HTTP satisfactoria.
Esta separación es importante. El webhook comunica una actualización del pago, pero tu aplicación sigue siendo responsable de decidir qué implica para el pedido, la cuenta, el envío o el asiento contable.
Antes de empezar
Prepara lo siguiente antes de conectar el callback:
- un endpoint HTTPS accesible públicamente que acepte solicitudes HTTP POST;
- acceso desde el servidor a las credenciales correspondientes del comercio en OxaPay, almacenadas de forma segura y nunca expuestas en el código del navegador;
- un registro en la base de datos que relacione el identificador de OxaPay
track_idwith your own order, invoice, or user ID; - reglas claras sobre qué estados de pago pueden activar la tramitación, el acceso, los reembolsos, las notificaciones o la revisión manual;
- registros y supervisión que permitan detectar fallos de entrega, errores de validación y cambios inesperados de estado.
Si estás planificando una integración más amplia, utiliza la lista de verificación de integración de pagos con criptomonedas to review keys, payment methods, callbacks, testing, and go-live controls together.
Cómo configurar los webhooks de OxaPay
Define las reglas de estados de pago
Decide qué debe hacer tu empresa ante cada estado del pago before writing the handler. A notification that a payment has started is not the same as a completed payment. Underpaid, expired, refunded, or other exception states may require a different action or a manual review.
Permite únicamente las transiciones de estado documentadas y previstas. Por ejemplo, un pedido ya tramitado no debe tramitarse de nuevo porque se haya entregado dos veces el mismo callback.
Crea un endpoint de callback seguro
Crea una ruta HTTPS específica en tu backend, como https://example.com/webhooks/oxapay. Debe aceptar solicitudes POST, conservar el cuerpo original de la solicitud para verificar la firma y rechazar métodos no admitidos o solicitudes malformadas.
Mantén el controlador centrado en su función. Su primera tarea es verificar y registrar de forma persistente el callback. Las tareas lentas, como enviar correos, actualizar varios sistemas externos o generar informes, pueden trasladarse a una cola en segundo plano una vez aceptado el evento.
Proporciona la URL de callback a OxaPay
Añade la URL de callback al flujo de pagos de OxaPay correspondiente. Según el producto o método de integración, la URL puede facilitarse en la solicitud de pago o en la configuración aplicable del comercio. Consulta la documentación de Webhooks de OxaPay for the exact field and behavior of the service you are implementing.
Utiliza siempre la misma URL dentro de cada entorno. Separa los endpoints de pruebas de los de producción para evitar que los eventos de prueba modifiquen pedidos reales.
Verifica la firma antes de confiar en el callback
OxaPay documenta una firma HMAC-SHA512 generada a partir de los datos POST originales y utilizando la clave API del comercio como secreto compartido. Tu servidor debe calcular la firma esperada a partir del cuerpo sin modificar y compararla con la firma recibida en el callback.
Rechaza la solicitud si falla la verificación. Utiliza una comparación de tiempo constante cuando tu framework lo permita y nunca registres la clave API del comercio ni otros secretos. Analizar el JSON y volver a serializarlo antes de calcular el HMAC puede alterar los espacios o el orden de los campos y hacer que falle una verificación válida. La referencia de verificación de callbacks explains the broader security model.
Identifica y valida el pago
Una firma válida confirma el origen del mensaje, pero tu aplicación también debe validar los datos de negocio. Vincula el identificador track_id to a known payment record, confirm the relevant order or customer reference, compare the expected amount and currency where applicable, and check that the new state is allowed from the current state.
No permitas que un pago desconocido, un importe inesperado o una transición de estado inválida active automáticamente la tramitación. Registra el evento para investigarlo y confirma la información actual del pago mediante la API.
Procesa cada evento de forma idempotente
Un webhook puede entregarse varias veces. Tu controlador debe producir el mismo resultado final si recibe la misma actualización de pago más de una vez. Guarda una clave estable del evento o del estado del pago y compruébala antes de enviar un correo, conceder acceso, modificar existencias o crear un asiento contable.
La idempotencia convierte una entrega duplicada en un reintento inofensivo, en lugar de provocar un envío duplicado, una ampliación repetida de la suscripción o un asiento doble.
Registra el evento y responde con rapidez
Una vez verificada la solicitud, guarda el callback y el resultado de su validación antes de devolver HTTP 200 with the expected ok response. If downstream work may take time, place it in a queue and respond after durable receipt rather than making the sender wait for the entire business workflow.
Si tu servidor no puede registrar el evento de forma segura, devuelve una respuesta de error e investiga el fallo. No confirmes la recepción de un callback para descartarlo después silenciosamente.
Prueba todo el ciclo de vida del pago
No te limites a probar un callback correcto. Incluye los estados y excepciones que pueda encontrar tu integración: pagos retrasados, insuficientes o caducados, entregas repetidas, firmas no válidas, valores desconocidos de track_id values, temporary database failure, and recovery after downtime.
Comprueba tanto el resultado técnico como el empresarial. El endpoint podría devolver 200 OK while the wrong order is updated or the customer receives two confirmations. A complete test follows the event from OxaPay through your database, queue, customer message, fulfillment logic, and audit trail.
Combina los webhooks con las consultas de estado
Los webhooks y las consultas de estado mediante API resuelven aspectos distintos del mismo problema. Un webhook proporciona una señal rápida. Una consulta de estado ofrece una vía de recuperación autorizada cuando el callback se retrasa, se pierde, se procesa fuera de orden o queda en situación incierta tras una caída local.
| Método | Uso recomendado | Limitación operativa |
|---|---|---|
| Callback de webhook | Reaccionar rápidamente a un cambio de estado del pago | La entrega puede retrasarse, repetirse o dejar de estar disponible temporalmente |
| Solicitud de información del pago | Recuperación, conciliación y confirmación del estado actual | Tu sistema debe decidir cuándo consultar y evitar las solicitudes periódicas innecesarias |
For important payment flows, schedule reconciliation for records that remain pending too long or have not received an expected update. OxaPay’s Payment Information API can be used to retrieve the current payment details by the documented identifier.
Casos prácticos de uso de webhooks
Pedidos de comercio electrónico
Mantén el pedido pendiente mientras se procesa el pago. Tras un estado de finalización verificado, reserva o libera el inventario según tus reglas de negocio, envía el pedido a preparación una sola vez y confirma el resultado al cliente.
SaaS y acceso digital
Activa la cuenta o amplía el acceso únicamente después de verificar el resultado del pago. Guarda el período pagado o el cambio de derechos para que un callback repetido no conceda dos veces el mismo beneficio.
Finanzas y conciliación
Añade los eventos de pago al registro de auditoría y relaciónalos con la factura interna. Los estados excepcionales pueden enviarse a una cola de revisión, mientras que las consultas programadas concilian los pagos que siguen sin resolverse.
Comunicación con el cliente
Envía los mensajes a partir del resultado de tu proceso de negocio idempotente, no directamente por cada callback entrante. Así evitas correos duplicados o mensajes contradictorios cuando un pago atraviesa distintos estados.
Errores habituales con los webhooks
- Confiar en la página de retorno: use verified server-side payment information instead of a browser redirect.
- Verificar JSON reformateado: calculate the HMAC from the original raw request body.
- Exponer la clave del comercio: keep signing credentials in protected server-side storage.
- Suponer que cada callback es único: make every business action idempotent.
- Hacer demasiado antes de responder: durably record the event, queue slow work, and respond promptly.
- Aceptar cualquier transición de estado: enforce a controlled payment state model.
- Depender solo de la entrega: use payment information requests for recovery and reconciliation.
- Registrar datos sensibles: retain useful identifiers and validation results without storing secrets unnecessarily.
Solución de problemas de webhooks de OxaPay
| Síntoma | Qué comprobar |
|---|---|
| No llega ningún callback | Comprueba la URL de callback, la accesibilidad pública por HTTPS, las reglas del cortafuegos, el entorno y los registros del pago correspondiente. |
| Falla la verificación de la firma | Usa los bytes originales de la solicitud, la clave API correcta del comercio, el método HMAC-SHA512 documentado y una comparación exacta. |
| La misma acción ocurre dos veces | Revisa la clave de idempotencia y asegúrate de registrar las acciones empresariales antes de que puedan repetirse. |
| El callback devuelve un error | Comprueba el análisis de datos, la disponibilidad de la base de datos, el estado de la cola, los errores de la aplicación y el tiempo de respuesta. |
| El estado local parece incorrecto | Consulta la información actual del pago, compara los identificadores y el historial de estados y después concilia el registro local. |
Lista de verificación para poner en producción los webhooks de OxaPay
- El callback de producción utiliza HTTPS y es accesible desde internet.
- Se conserva el cuerpo original de la solicitud hasta completar la verificación HMAC-SHA512.
- La clave API del comercio se almacena de forma segura y nunca aparece en el código del cliente ni en los registros.
- Cada callback se vincula a un pago conocido y se valida con los datos de negocio esperados.
- Las transiciones de estado de pago permitidas están documentadas y se aplican.
- Los callbacks repetidos no pueden duplicar la tramitación, el acceso, las notificaciones ni los asientos contables.
- Se registran los eventos y resultados de validación sin incluir datos sensibles innecesarios.
- Los pagos retrasados o inciertos pueden conciliarse mediante la Payment Information API.
- La supervisión avisa al equipo de fallos de firma, errores de procesamiento y acumulación en las colas.
- Se ha probado todo el flujo antes de que los pagos reales de los clientes dependan de él.
¿Qué viene después?
Empieza por definir la acción empresarial permitida para cada estado de pago. Después crea un endpoint seguro que verifique, registre y elimine duplicados de los callbacks antes de activar tareas posteriores. Por último, incorpora consultas de estado y conciliación para que un fallo temporal de entrega o del sistema no deje un pedido sin resolver indefinidamente.
Para profundizar en los estados de pago, la entrega y la arquitectura de recuperación, lee Monitorización en tiempo real en sistemas de pago blockchain. Los desarrolladores deben mantener la documentación actual de webhooks de OxaPay as the implementation source of truth.
