Webhooks
Webhooks de procesamiento de pagos, que permiten notificaciones HTTP en tiempo real para la sincronización a través de más de 50 socios adquirentes, automatizando el cumplimiento y rastreando instantáneamente eventos de contracargo o actividad MID.
- Categoría
- Desarrollador
- Capacidades
- 6
- Disponible en
- Todos los planes
Los webhooks proporcionan notificaciones en tiempo real y basadas en eventos para actualizaciones críticas del ciclo de vida de los pagos. Los webhooks de Cardflo permiten que sus sistemas reaccionen instantáneamente a los estados de pago, disputas y otros eventos clave.
Automatice los flujos de trabajo y mantenga la sincronización entre su plataforma y Cardflo sin sondeos constantes.
Las notificaciones oportunas de webhook ofrecen actualizaciones en tiempo real sobre el estado de las transacciones y la actividad de MID en nuestra extensa red de adquirentes. Este flujo de datos instantáneo permite la automatización rápida de procesos comerciales críticos y respuestas inmediatas a eventos.
Acerca de Webhooksresumen
Los webhooks funcionan como devoluciones de llamada HTTP asíncronas que facilitan la comunicación en tiempo real entre una pasarela de pagos y un servidor comercial.
A diferencia de los métodos de sondeo tradicionales, donde un servidor realiza solicitudes repetitivas para verificar las actualizaciones de estado, los webhooks envían datos a una URL predefinida en el momento en que ocurre un evento específico dentro del ciclo de vida del pago.
Este mecanismo es crítico para gestionar eventos no síncronos como los resultados de autenticación 3D Secure, las finalizaciones asíncronas de métodos de pago alternativos (APM) o la recepción de un contracargo.
Dentro de la pila de pagos, los webhooks actúan como el tejido conectivo entre el adquirente o PSP y el sistema interno de gestión de pedidos (OMS) o la plataforma de gestión de ingresos del comerciante.
Aseguran que la lógica posterior, como el bloqueo de inventario o el derecho digital, permanezca precisa sin introducir latencia o sobrecarga innecesaria de la API.
La implementación adecuada requiere un manejo robusto de los códigos de estado HTTP y la idempotencia para gestionar posibles reintentos desde el servidor de envío, asegurando que cada evento se procese una y solo una vez.
Cómo funciona Webhooksfunciona
Definir punto final y eventos
Un comerciante especifica una URL de destino dentro de su entorno para recibir solicitudes POST. Selecciona disparadores de eventos específicos del ciclo de vida del pago, como el éxito de la autorización, el inicio del reembolso o la creación de disputas. Esto garantiza que su sistema solo procese paquetes de datos relevantes, reduciendo la carga innecesaria del servidor y manteniendo los puntos de integración enfocados y manejables.
Disparador de eventos y carga útil
Cuando ocurre un cambio de estado, como que un cliente complete un desafío SCA, el sistema genera una carga útil JSON. Esta carga útil contiene datos estructurados, incluyendo el ID de transacción, el ID de comerciante (MID), el monto y el tipo de evento específico. Luego, la pasarela intenta entregar estos datos al punto final registrado.
Seguridad y verificación de firma
Para evitar la inyección de datos no autorizados, la carga útil se firma típicamente con una clave secreta. El servidor comercial reconstruye la firma utilizando el cuerpo de la solicitud sin procesar y la compara con la cabecera. Esta verificación asegura que los datos se originaron en la fuente confiable y no fueron manipulados durante el tránsito.
La importancia de Webhooksimporta
Eficiencia operativa y automatización
Confiar en verificaciones de estado manuales o sondeos periódicos de la API introduce una latencia que puede degradar la experiencia del usuario y retrasar el cumplimiento. Los webhooks automatizan la transición entre la autorización de pago y la entrega del servicio. Al recibir una notificación inmediata de capturas o liquidaciones exitosas, las empresas pueden automatizar los flujos de trabajo de envío, la generación de licencias o el aprovisionamiento de cuentas, reduciendo la necesidad de intervención manual y minimizando el riesgo de error humano en la gestión de transacciones.
Mitigación de riesgos y disputas
Las notificaciones de solicitudes de recuperación o contracargos permiten a los comerciantes responder dentro de los plazos establecidos por el esquema. Las alertas inmediatas sobre rechazos suaves o fallos de SCA permiten una interacción proactiva con el cliente. Al reaccionar a estos eventos a medida que ocurren, los comerciantes pueden mejorar sus tasas de éxito de representación y reducir los costos operativos asociados con fallos de pago no abordados o disputas que de otro modo podrían haber pasado desapercibidas hasta una auditoría manual periódica.
Notas regulatorias sobre Webhooks
Data privacy and payload security
Transmitting transaction data across open networks leaves no slack against data protection regulations like GDPR and PCI DSS. Notification payloads must travel exclusively over TLS-encrypted connections to prevent interception by unauthorised third parties during transit.
Cardflo enforces HTTPS URLs for all registered listener endpoints, rejecting any unencrypted destinations.
Furthermore, structured notifications exclude sensitive cardholder data, such as full primary account numbers or security codes. The gateway transmits tokenised identifiers and masked references, ensuring that the receiving server does not inadvertently bring its hosting environment into the highest tiers of PCI DSS compliance scope.
PSD2 and asynchronous strong customer authentication
Under Payment Services Directive 2, Strong Customer Authentication introduces asynchronous flows into the standard checkout process. When a transaction requires an out-of-band authentication step, such as a biometric check in a banking application, the initial request cannot return an immediate definitive success or failure status.
Event listeners are essential for capturing the final outcome of these mandated security challenges. Once the issuing bank confirms the authentication result through the acquirer partner network, the orchestration layer fires an asynchronous event.
This notification informs the merchant system that the security requirement is satisfied and the capture can proceed.
Casos de uso de Webhookscasos de uso
Ciclo de vida de suscripciones y SaaS
Cuando un pago recurrente falla o una tarjeta caduca, un webhook activa una secuencia de cobro automatizada o suspende el acceso del usuario, manteniendo ciclos de facturación precisos sin supervisión manual.
Cumplimiento de pedidos de comercio electrónico
Un minorista en línea utiliza webhooks para liberar productos para el envío solo después de recibir un evento 'capture.succeeded', evitando el envío de artículos para los cuales el pago no ha sido completamente autorizado.
Coordinación de pagos del marketplace
Las plataformas que reciben fondos pueden activar desembolsos a subcomerciantes solo después de que la transacción inicial del cliente alcance un estado liquidado, asegurando la liquidez y reduciendo el riesgo de reversiones de pagos.
Finalización del método de pago alternativo
Para métodos como transferencias bancarias o esquemas locales que no proporcionan confirmación instantánea, los webhooks notifican al sistema horas o días después cuando se confirman los fondos.
Webhooks en cifras
Retraso típico de la industria entre el registro de un evento en la plataforma adquirente y el envío del webhook al punto final del comerciante.
Referencia de fiabilidad estándar para los servicios de webhook cuando se incluye lógica de reintento automatizada e infraestructura de entrega redundante.
Observación de la industria sobre la mejora en la velocidad de cumplimiento al pasar del procesamiento por lotes periódico a arquitecturas de webhook basadas en eventos.
Metodología: estas cifras son rangos ilustrativos extraídos de datos publicados de la industria y cohortes de comerciantes observadas, y no constituyen garantías. Los resultados reales dependen de su perfil de riesgo, combinación de tarjetas, geografía y configuración de adquirencia, y solo se confirman en sus propios términos de precios y aprobación.
Términos relacionados
Habla con nuestro equipo sobre una implementación en vivo en los rails de nuestros socios adquirentes.
Lo que obtienes con Webhooks
- Entrega asíncrona de cambios de estado de transacción para un rendimiento mejorado del sistema.
- Soporte para múltiples tipos de eventos, incluyendo autorización, captura, reembolso y disputa.
- Cabeceras de firma HMAC-SHA256 para una verificación robusta de la integridad de los datos entrantes.
- Lógica de reintento automatizada siguiendo programaciones de retroceso exponencial para intentos de entrega fallidos.
- Control de versiones de la carga útil para garantizar la compatibilidad a medida que las estructuras de datos evolucionan con el tiempo.
- Capacidades de lista blanca de IP para restringir el tráfico entrante a fuentes de pasarela conocidas.
A short scoping call, then a written plan for your MIDs.
Preguntas sobre Webhooks
¿Cómo debe manejar nuestro servidor las notificaciones de webhook duplicadas?
Es una práctica estándar que las pasarelas de pago empleen un mecanismo de reintento si un punto final no devuelve una respuesta 200 OK dentro de un plazo específico. En consecuencia, su servidor puede recibir el mismo evento varias veces.
Para mantener la integridad de los datos, debe implementar una lógica de idempotencia. Esto generalmente implica rastrear el ID de evento único proporcionado en la carga útil y verificar si ya se ha procesado antes de ejecutar cualquier lógica de negocio.
Si el ID existe en su base de datos, su servidor debe ignorar el evento pero aún así devolver un 200 OK para detener futuros reintentos.
¿Cuál es la diferencia entre sondear una API y usar webhooks?
El sondeo requiere que su servidor inicie solicitudes frecuentes a la pasarela para verificar las actualizaciones de estado, lo cual es ineficiente y puede provocar problemas de limitación de velocidad o información retrasada.
Los webhooks invierten este flujo, donde la pasarela inicia una solicitud a su servidor solo cuando ocurre un evento.
Este modelo de 'push' es más eficiente, reduce la carga del servidor y garantiza que los estados se actualicen casi en tiempo real en toda su infraestructura,
lo cual es particularmente importante para acciones sensibles al tiempo como la entrega de contenido digital o la prevención de fraudes.
¿Por qué es necesaria la verificación de la firma para cada solicitud de webhook?
Dado que los puntos finales de webhook son URL públicas, son teóricamente accesibles por cualquier entidad en Internet. Sin verificación, un atacante podría enviar una carga útil JSON falsificada a su servidor, indicando falsamente que un pago de alto valor fue exitoso.
Al usar un secreto compartido para verificar la firma HMAC proporcionada en la cabecera de la solicitud, su sistema puede probar matemáticamente que el mensaje fue enviado por su PSP y que el contenido no ha sido alterado,
garantizando la seguridad de su proceso de cumplimiento de pedidos.
¿Cómo manejan los webhooks los requisitos de 3D Secure y SCA?
Durante un flujo 3-DS, la transacción a menudo pasa a un estado pendiente mientras el usuario es redirigido a su emisor para la autenticación. El resultado final de esta autenticación puede no conocerse de inmediato.
Los webhooks se utilizan para notificar a su sistema cuando se completa el desafío 3-DS y la transacción es posteriormente autorizada o denegada.
Esto evita que su proceso de pago se quede colgado y permite que su backend reaccione al estado de autorización final una vez que el cliente regresa de la página de redirección del banco.
Características relacionadas.
Guías relacionadas.
Vea cómo Cardflo se compara.
¿Listo para mejorar tu configuración de pagos?
Cuéntenos sobre su negocio. Le emparejaremos con los socios adquirentes adecuados y la ruta correcta, normalmente en una semana.