Webhooks
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.
- Categoría
- Desarrollador
- Capacidades
- 10
- Disponible en
- Todos los planes
La visión general
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 3-D 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
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.
Reconocer y procesar
El servidor comercial debe devolver un código de estado 200 OK rápidamente para confirmar la recepción. Luego se ejecuta la lógica interna, como actualizar un registro de la base de datos o activar un correo electrónico automatizado.
Si el servidor está fuera de línea o devuelve un error, el sistema de entrega sigue un programa de reintentos programado para garantizar la coherencia de los datos.
Por qué importa
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.
Casos 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.
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.
Términos relacionados
Talk to our team about a live rollout on your acquiring stack.
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.
- Inclusión de clave de idempotencia para evitar el procesamiento duplicado del mismo evento de pago.
- Registros de eventos detallados para depurar y auditar el rendimiento de la entrega de webhooks dentro del panel de control.
- Selección granular de eventos para minimizar el uso de ancho de banda y los requisitos de procesamiento del lado del servidor.
- Funcionalidad de modo de prueba para validar el comportamiento del punto final con escenarios de pago simulados.
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 3-D 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.
¿Se pueden usar los webhooks para gestionar los plazos de contracargos y disputas?
Sí, los webhooks son una herramienta principal para gestionar el ciclo de vida de las disputas. Cuando un titular de tarjeta inicia una Solicitud de Recuperación o un Contracargo formal con su emisor, la pasarela recibe esta notificación a través de los esquemas de tarjetas.
Luego se envía un webhook a su sistema especificando el código de motivo, el monto y la fecha límite para la respuesta.
Utilizando estos datos en tiempo real, puede automatizar la suspensión de la cuenta relevante y notificar a su equipo de riesgos para que inicie el proceso de representación de inmediato, aumentando la probabilidad de una reversión exitosa de la disputa.
¿Qué sucede si nuestro servidor está inactivo durante un evento de webhook crítico?
Los sistemas de webhook confiables operan con una política de reintentos. Si su punto final devuelve un error 4xx o 5xx, o no responde en unos pocos segundos, la pasarela pondrá el mensaje en cola para su reentrega.
Estos reintentos suelen seguir un patrón de retroceso exponencial, intentando la entrega varias veces durante minutos u horas.
Para garantizar la coherencia a largo plazo, también debe tener un mecanismo de respaldo, como un script de conciliación diario que llama a la API para encontrar cualquier cambio de estado perdido, proporcionando una red de seguridad para interrupciones prolongadas.
Características relacionadas.
¿Listo para la velocidad?
Cuéntanos sobre tu negocio. Te pondremos en contacto con los socios adquirentes y la ruta adecuada, normalmente en una semana.