Webhooks, APIs y polling para Product Managers

Un webhook permite que un sistema avise a otro cuando ocurre un evento. El polling consiste en consultar repetidamente una API para comprobar si algo ha cambiado. Ambos pueden formar parte de la misma integración: el webhook comunica un cambio y una petición a la API permite recuperar detalles o comprobar el estado actual. La comparación «webhook frente a API» necesita, por tanto, una pregunta más precisa: ¿cómo debe enterarse este producto de que algo ha ocurrido?

La respuesta afecta al tiempo que espera el cliente, al número de peticiones de la integración y a cómo se recupera cuando un mensaje se retrasa. La confirmación de un pago ofrece un ejemplo útil porque la diferencia se hace visible: el pago puede haberse completado mientras la tienda sigue mostrando el pedido como pendiente.

Una petición a la API y una notificación parten de sitios distintos

En una interacción habitual con una API HTTP, una aplicación envía una petición a un servicio y recibe una respuesta. Puede consultar el estado actual de un pedido o solicitar la creación de un pago. Un endpoint es la dirección en la que el servicio acepta un determinado tipo de petición. La aplicación que lo llama decide cuándo preguntar, dentro de las reglas y los límites de acceso del servicio.

Con un webhook, el sistema donde ocurre el evento envía una petición a un endpoint de la aplicación receptora. Un proveedor de pagos puede avisar al backend de una tienda cuando un pago se completa, sin esperar a que la tienda vuelva a preguntar. El receptor debe verificar y procesar la notificación. El propio webhook suele entregarse mediante una petición HTTP; no sustituye a toda la API.

Los dos mecanismos también pueden cumplir funciones distintas en una transacción. Una petición a la API puede iniciar el pago y un webhook comunicar un resultado posterior. GitHub documenta otro caso: un evento de un repositorio puede avisar a un servicio externo y activar trabajo allí. En ambos ejemplos, los eventos disponibles y sus reglas de entrega dependen del proveedor.

Un pago pendiente y dos formas de conocer su resultado

En un checkout hipotético de Mercato, una plataforma de comercio electrónico, el backend crea un pago mediante la API del proveedor, guarda su referencia junto al pedido y recibe un resultado pendiente. El cliente ve que el pago se está procesando. El backend necesita saber cuándo cambia ese estado, sin interpretar «pendiente» como un fallo ni como un éxito.

Con polling, Mercato programa consultas periódicas para conocer el estado actual del pago. Si en este ejemplo consulta cada treinta segundos, un cambio que ocurra justo después de una comprobación normalmente no se descubrirá hasta la siguiente consulta correcta. Los retrasos de red, los límites de peticiones y los errores pueden alargar ese intervalo. Aumentar la frecuencia puede reducir la espera, pero también incrementa las consultas, incluidas aquellas cuya respuesta sigue sin cambiar.

Con un webhook, el proveedor envía una notificación cuando ocurre el evento correspondiente. Mercato la verifica, la relaciona con el pago almacenado y actualiza el pedido. Esto puede reducir el retraso sin consultar repetidamente cada pago, aunque la notificación todavía tiene que entregarse y procesarse. No garantiza que la pantalla se actualice al instante.

El navegador del cliente es otra parte de este recorrido. Un webhook del proveedor normalmente llega a un endpoint del backend, no a la página que el cliente tiene abierta. Mercato también debe decidir cómo conoce esa página el nuevo estado del pedido, por ejemplo consultando el backend de Mercato mientras el pago esté pendiente. Ese polling del navegador es distinto de que el backend consulte repetidamente al proveedor de pagos externo.

Comparar polling y webhooks según la necesidad del producto

Cómo conoce una integración un cambio de estado
Decisión	Polling a una API	Notificación por webhook
¿Quién inicia el intercambio?	La aplicación que quiere comprobar el estado.	El sistema que comunica un evento.
¿De qué depende el retraso?	Del intervalo entre consultas, el tiempo de respuesta y los posibles fallos.	De la generación, entrega y procesamiento del evento, incluidos los reintentos.
¿Qué genera tráfico?	Las consultas programadas, aunque no haya novedades.	Los eventos suscritos y sus posibles entregas repetidas.
¿Qué debe mantener el receptor?	La programación de consultas, el acceso a la API y la gestión de errores y límites.	Un endpoint accesible, la verificación de las entregas y un procesamiento fiable.
¿Qué información recibe?	El estado que devuelve la consulta cuando se procesa.	Información sobre un evento; puede necesitar otra consulta a la API.

El polling puede encajar cuando no existe un webhook adecuado, los cambios son poco frecuentes o el retraso permitido hace suficientes las consultas programadas. Una sincronización administrativa diaria tiene requisitos distintos de los de un cliente que espera en el checkout. También hay que comprobar si el proveedor permite el volumen de llamadas necesario y si el sistema receptor puede mantener un endpoint para webhooks.

Un cálculo hipotético permite ver el efecto sobre el tráfico: consultar 1.000 pagos pendientes una vez por minuto genera unas 1.000 peticiones de estado por minuto si cada pago necesita una llamada independiente. Un endpoint por lotes, menos pagos pendientes o un intervalo mayor cambiarían esa cifra. Es un ejemplo para dimensionar la integración, no una medición ni una afirmación sobre los límites de cualquier proveedor.

Los fallos de entrega forman parte del recorrido de pago

Un webhook puede retrasarse, entregarse varias veces o llegar después de otro evento relacionado. La documentación del proveedor define las garantías y las opciones de recuperación reales. Stripe, por ejemplo, documenta las entregas duplicadas y no garantiza el orden de los eventos. El receptor no debería dar por hecho que la última notificación recibida describe el estado más reciente.

En el ejemplo de Mercato, recibir de nuevo una notificación de pago correcto no debe enviar el mismo pedido dos veces a preparación. El equipo necesita reglas que permitan procesar con seguridad una entrega repetida, incluida la identificación de eventos ya procesados y la protección de la propia operación de negocio. Esta propiedad se llama idempotencia: repetir la misma operación no produce un efecto adicional. El identificador del evento ayuda a detectar reenvíos, pero también importan las reglas de procesamiento del pedido.

Ese problema es distinto de reintentar la petición a la API que crea un pago. Algunos proveedores aceptan una clave de idempotencia para reconocer que un reintento corresponde a la misma petición. Stripe documenta ese mecanismo y sus límites. Un receptor de webhooks que gestiona bien los duplicados no impide, por sí solo, que dos peticiones independientes de creación de pago cobren dos veces al cliente.

El receptor también debe comprobar de dónde procede la notificación antes de cambiar el estado de un pedido. Algunos proveedores ofrecen notificaciones firmadas; Stripe documenta la verificación de firmas y las comprobaciones frente a mensajes reenviados de forma maliciosa. El requisito de producto es que una petición entrante no fiable no pueda marcar un pedido como pagado. La clave de API para llamar al proveedor y el secreto utilizado para verificar sus webhooks pueden ser credenciales distintas.

La recuperación puede combinar notificaciones y consultas a la API

Mercato puede utilizar webhooks para las actualizaciones habituales y un proceso de recuperación programado para investigar pagos que siguen pendientes más tiempo del esperado. Ese proceso puede consultar la API del proveedor y reconciliar el registro local con el estado de referencia del pago. Su frecuencia debe tener en cuenta los métodos de pago utilizados: un pago legítimamente lento no debería clasificarse como una incidencia solo por tardar más que un pago con tarjeta.

La política de recuperación debe explicar qué ocurre si el endpoint de webhooks no está disponible, si el proveedor reintenta las entregas y cómo se localizan o reenvían los eventos perdidos. También debe distinguir entre recibir correctamente un mensaje y completar el trabajo de negocio. Un endpoint puede confirmar la recepción después de aceptar la notificación en una cola persistente y procesarla más tarde; observar únicamente las respuestas de entrega dejaría fuera un proceso de trabajo detenido.

Para el cliente, el requisito podría traducirse en una pantalla de pago pendiente con una forma segura de consultar el progreso y una vía de soporte cuando se supera la espera prevista. El texto y los tiempos concretos dependen del método de pago. Mostrar un fallo solo porque no ha llegado una notificación puede provocar un segundo intento mientras el primero sigue resolviéndose.

Decisiones que conviene registrar antes de implementar

La definición de la integración debe indicar con qué rapidez necesita el producto conocer un cambio y qué sistema mantiene el estado de referencia. Esos requisitos permiten a Ingeniería elegir el recorrido habitual de actualización y su recuperación. La revisión puede abordar entonces casos concretos:

¿Qué eventos del proveedor hacen falta y contienen información suficiente para actualizar el pedido?
¿Cómo verificará el receptor las notificaciones y las asociará con el cliente y el pago correctos?
¿Qué evita que un mensaje duplicado o fuera de orden active una acción de negocio incorrecta?
¿Cómo se detectarán, investigarán y recuperarán las actualizaciones retrasadas o perdidas?
¿Qué verá el cliente mientras el resultado siga siendo incierto y qué podrá comprobar soporte?

La guía de APIs para Product Managers explica el modelo general de peticiones y respuestas. Para entender el efecto de las consultas repetidas sobre el volumen permitido, puede consultarse límites de peticiones de API. El diagrama de arquitectura de un checkout sitúa el frontend, el backend y el proveedor en el mismo recorrido.

El libro APIs para Product Managers desarrolla las decisiones de integración, los permisos y la gestión de errores con más detalle.