¿Qué es un webhook?

¿Qué es un webhook?

Un webhook es una notificación automatizada enviada de un sistema a otro cuando ocurre algo concreto. En lugar de que su sistema pregunte constantemente "¿ha cambiado algo?" (lo que se llama polling), un webhook invierte el modelo: el otro sistema avisa al suyo cuando ocurre algo, justo en el momento en que ocurre.

Una analogía sencilla. Imagine que espera un paquete. Podría asomarse a la puerta cada cinco minutos para ver si ha llegado (eso es polling), o instalar un timbre que el repartidor pulse al llegar (eso es un webhook). El timbre es claramente más eficiente: solo actúa cuando realmente hay algo que hacer.

En el mundo de los pagos, los webhooks son el mecanismo por el que los proveedores de pago avisan a su sistema de los eventos en tiempo real. Un pago se completó. Un cargo recurrente falló. Un cliente disputó una transacción. Se procesó un reembolso. Cada uno puede disparar un webhook que su sistema recibe y maneja automáticamente.

Cómo funcionan los webhooks

El funcionamiento es sorprendentemente sencillo:

Configuración

Registra una URL de webhook en el proveedor (en este caso, su proveedor de pagos). Esa URL es un endpoint en su servidor, una dirección web a la que su sistema escucha listo para recibir mensajes entrantes. La mayoría de proveedores permiten configurar qué eventos dispararán webhooks, así que solo recibe los que le interesan.

Se produce el evento

Algo ocurre en el sistema del proveedor: se completa un cargo, falla un pago, se cancela una suscripción, se abre una disputa. El proveedor detecta el evento y prepara la notificación.

Se envía la notificación

El proveedor envía una petición HTTP POST a su URL de webhook. El cuerpo de la petición contiene datos sobre el evento (normalmente en formato JSON): tipo de evento, ID de transacción, importe, marca temporal y cualquier otra información relevante.

Su sistema responde

Su servidor recibe el webhook, procesa los datos, toma la acción necesaria (actualizar una base de datos, enviar un correo, disparar un proceso de cumplimiento) y devuelve una respuesta al proveedor confirmando la recepción. Esa respuesta suele ser un código HTTP 200, que significa "recibido".

Lógica de reintentos

Si su servidor no responde (quizá esté caído o sobrecargado temporalmente), el proveedor reintentará el webhook varias veces durante horas o días. Los calendarios de reintento varían, pero por lo general se van espaciando: el primer reintento puede ser tras unos minutos, el siguiente tras una hora, y así sucesivamente.

Por qué importan los webhooks en pagos

Los webhooks resuelven varios problemas importantes:

Actualizaciones en tiempo real

Sin webhooks, su sistema tendría que consultar periódicamente la API del proveedor para saber qué ha ocurrido. Este enfoque (polling) malgasta recursos (la mayoría de consultas no devuelve información nueva), introduce retrasos (solo se entera en el siguiente intervalo) y carga innecesariamente su sistema y la API del proveedor. Los webhooks lo eliminan todo entregando las actualizaciones al instante.

Manejo de eventos asíncronos

Muchos eventos de pago no ocurren en el punto de venta. Un cliente puede disputar una transacción días o semanas después. La renovación de una suscripción puede fallar porque la tarjeta caducó. Un reembolso puede tardar varios días. Los webhooks permiten que su sistema se mantenga informado de esos eventos según ocurren, sin necesidad de revisarlos manualmente.

Automatización de procesos de negocio

Los webhooks son el mecanismo de disparo para la automatización. Cuando se dispara un webhook de pago, su sistema puede actualizar automáticamente el estado de la cuenta del cliente, enviar un recibo o correo de confirmación, lanzar el envío, actualizar la contabilidad, avisar al equipo si hay que prestar atención o reintentar un pago fallido con retraso. Sin webhooks, todo eso requeriría intervención manual o polling constante, ambos ineficientes y propensos a errores.

Eventos habituales de webhook de pagos

La mayoría de proveedores ofrecen webhooks para un conjunto estándar de eventos. Aunque los nombres varían, los típicos incluyen:

• payment.completed: un pago se procesó correctamente.
• payment.failed: un intento de pago fue rechazado o falló.
• payment.refunded: se emitió un reembolso.
• subscription.created: se creó una nueva suscripción.
• subscription.cancelled: se canceló una suscripción.
• subscription.payment_failed: falló un pago recurrente.
• dispute.created: un cliente disputó una transacción.
• dispute.resolved: se resolvió una disputa (ganada o perdida).
• payout.completed: los fondos se liquidaron en su cuenta bancaria.

Consideraciones de seguridad

Como los webhooks implican recibir datos desde una fuente externa, la seguridad es crítica. Debe poder confiar en que el webhook venga realmente del proveedor y no esté suplantado. La mayoría lo gestionan con firmas: cada petición incluye una firma criptográfica que su servidor puede verificar con una clave secreta compartida. Verifique siempre las firmas antes de procesar los datos.

Otras buenas prácticas: usar HTTPS en su endpoint para cifrar los datos en tránsito, validar la estructura del payload antes de procesarlo, implementar límites de tasa para protegerse de inundaciones de webhooks y nunca confiar en los datos del webhook para operaciones sensibles sin contrastarlos con la API del proveedor (por ejemplo, si un webhook dice que un pago fue exitoso, confirme con la API antes de enviar la mercancía).

Relevancia para los pagos por teléfono

Los webhooks son tan importantes para los pagos por teléfono como para los pagos en línea. Cuando un cliente paga por teléfono en una plataforma segura, la transacción genera los mismos tipos de eventos que un pago en línea, y los webhooks entregan notificaciones en tiempo real.

Para los negocios que gestionan pagos por teléfono, los webhooks habilitan flujos muy valiosos. Cuando un pago telefónico se completa, un webhook puede actualizar la pantalla del agente con la confirmación, eliminando la necesidad de comprobar manualmente. Si un pago telefónico falla, un webhook puede alertar al agente para que pida otra tarjeta. Tras la llamada, los webhooks pueden disparar correos automáticos o SMS de confirmación, crear entradas en el CRM y actualizar la facturación, todo sin introducir datos manualmente.

Esto es especialmente valioso en centros de contacto con grandes volúmenes de llamadas. Sin webhooks, los agentes tendrían que comprobar manualmente los estados, actualizar registros y enviar confirmaciones. Los webhooks lo automatizan y permiten al agente centrarse en el cliente.

Consideraciones prácticas

• Verifique siempre las firmas para asegurarse de que el webhook viene realmente de su proveedor de pagos.
• Diseñe su manejador de webhooks para que sea idempotente: si el mismo webhook se entrega dos veces (por un reintento), su sistema debe tolerarlo sin duplicar acciones.
• Responda rápido a los webhooks (en pocos segundos) con un código 200 y procese después los datos de forma asíncrona si es necesario. Las respuestas lentas pueden provocar reintentos innecesarios.
• Registre todos los webhooks recibidos para depuración y auditoría.
• Configure monitorización para que su equipo reciba alertas si fallan las entregas o si su endpoint deja de responder.
• Tenga un mecanismo de respaldo (como polling periódico de la API) para procesos críticos, por si la entrega de webhooks se interrumpe.
• Mantenga la lógica del endpoint sencilla y robusta: un fallo en el manejador puede provocar caídas en cascada en su flujo de pago.
• Pruebe su integración a fondo, incluidos escenarios de fallo y de reintento.

Los webhooks son una de esas tecnologías que mejor funcionan cuando no se notan. Bien configurados, la información fluye sin fricción entre el proveedor y sus sistemas, los eventos se manejan automáticamente y su equipo está informado sin mover un dedo. Mal configurados (o no configurados), se acaban con procesos manuales, información retrasada y eventos perdidos. Para cualquier negocio que acepte pagos, invertir en una integración sólida de webhooks es tiempo bien empleado.