Webhook vs API para integraciones en recintos: guía práctica
Webhook vs API explicado para equipos de recintos y hostelería. Compare latencia, fiabilidad y seguridad, y descubra cuál elegir para WiFi, TPV, reservas y estancias.
Lleva seis semanas en un despliegue en múltiples instalaciones. La captura de WiFi está activa, las cajas están conectadas, las reservas fluyen y el equipo de marketing quiere algo muy sencillo: cuando un invitado compre, reserve, se conecte al WiFi o deje la habitación, envíele el mensaje adecuado en el momento oportuno. De repente, un webhook de compra llega dos veces y emite dos ofertas de uso único. Un inicio de sesión WiFi desaparece durante el reinicio del receptor. Nadie eligió un mal proveedor. Trató la decisión de webhook vs API como una elección entre dos conductos intercambiables, y el entorno de producción dejó al descubierto la diferencia.
Índice de contenidos
- Por qué los equipos de recintos se equivocan al elegir
- Qué hacen realmente los Webhooks y las APIs
- Comparación entre Webhooks y APIs según los criterios clave
- Qué patrón se adapta a cada evento del recinto
- Diseño de un receptor que no falle en producción
- Por qué la elección real es Webhook más API
Por qué los equipos de los recintos se equivocan en esta elección
Un grupo de restauración conecta Purple WiFi para los inicios de sesión, Square o Epos Now para los recibos, ResDiary para las reservas y, para su negocio hotelero, Mews para las estancias. Cada proveedor afirma que admite la integración. Cada uno se refiere a algo ligeramente diferente. Uno envía eventos automáticamente (push), otro espera que los consulte (poll), y otro hace ambas cosas pero con campos y comportamientos de reintento distintos.
El equipo configura primero la vía más rápida. Una venta en el TPV activa un flujo de agradecimiento con una oferta. El TPV no recibe una respuesta lo suficientemente rápida, lo reintenta y el receptor procesa la misma venta de nuevo porque nunca almacenó el ID del evento. El cliente recibe dos mensajes y, lo que es peor, dos códigos canjeables.
El evento no recibido es el fallo más silencioso
El mismo fin de semana, el receptor está fuera de línea por un despliegue. Las conexiones WiFi se encolan en el emisor durante un tiempo, y luego se agotan los intentos. No hay ninguna lectura programada de la API para recuperarlas, por lo que esos huéspedes nunca entran en la secuencia de bienvenida. Los informes parecen ligeramente reducidos, no rotos. Nadie avisa a nadie por las altas que faltan.
Regla práctica: Considere un webhook como una señal de que algo puede haber ocurrido, no como una prueba del estado actual. Verifique el estado antes de enviar, emitir o canjear cualquier elemento.
No se trata de casos aislados. Es el comportamiento habitual de los sistemas distribuidos, tal como se describe en esta guía sobre la combinación de webhooks con API para la recuperación. La entrega es por lo general al menos una vez, los eventos pueden llegar con retraso o desordenados, y un receptor no disponible genera vacíos de información a menos que haya diseñado un proceso de conciliación.
Los equipos de los recintos se equivocan en esto por tres razones comprensibles.
- Se preguntan qué herramienta es mejor: La pregunta útil es qué patrón se adapta a cada evento (inicio de sesión en WiFi, venta en TPV, reserva o pago) según su necesidad de latencia y el coste del error.
- Confían a ciegas en la carga útil: Una carga útil es una instantánea en el momento del envío. El consentimiento, la elegibilidad y el gasto pueden cambiar antes de que un reintento se efectúe horas más tarde.
- Omiten la recuperación: Las demostraciones en situaciones ideales no muestran entregas duplicadas, reordenamientos o un receptor que no está operativo durante el servicio de un sábado.
Este es un informe de trabajo para responsables de TI, datos y CRM en restaurantes, hoteles y tiendas minoristas. Encontrará el funcionamiento básico, una comparación criterio por criterio, una recomendación evento por evento y el diseño de receptor que nos gustaría revisar antes de cualquier lanzamiento multiubicación. El objetivo no es declarar un ganador en webhook vs API. Es evitar campañas duplicadas y trayectorias de usuario no capturadas.
Qué hacen realmente los webhooks y las API
Comience por determinar quién inicia la llamada. Ese único dato explica la mayor parte de las ventajas y desventajas posteriores.
Una API utiliza un modelo de extracción (pull). Su cliente envía una solicitud HTTP cuando necesita datos o quiere realizar una acción, y el servidor responde. Un webhook utiliza un modelo de empuje (push). El sistema de origen envía una solicitud HTTP a un extremo preconfigurado por usted cuando ocurre un evento, como una compra, una reserva, una suscripción o la actualización de una cuenta. Esta distinción se detalla en el estudio State of Webhooks de Svix sobre la adopción de proveedores de API.
La analogía del recinto se sostiene perfectamente. Una API es como pedirle al camarero el menú cuando a usted le apetece. Un webhook es como el camarero trayéndole su plato cuando está listo, sin que tenga que llamar a nadie.
El funcionamiento interno que está configurando
Ambos patrones utilizan HTTP, suelen transportar cargas útiles JSON, transmiten metadatos en los encabezados y comunican el éxito o el error mediante códigos de respuesta. La dirección se invierte, y lo mismo ocurre con la carga operativa. Con una API, usted conserva las credenciales, elige el momento y gestiona la paginación y los límites de tasa. Con un webhook, expone una URL accesible públicamente, autentica tráfico entrante que no ha iniciado y debe responder rápidamente bajo una carga de trabajo que no controla.
- Venta en TPV: La caja registradora envía un webhook cuando se cierra una transacción, para que un recibo o una secuencia de opiniones puedan iniciarse sin necesidad de consultar constantemente cada caja.
- Historial de estancias: Su plataforma llama a la API del PMS para obtener las estancias anteriores de un huésped, conciliar un registro de salida o recuperar los datos de una semana que faltaba.
- Actualización de segmentos: Una plataforma de marketing extrae registros actualizados a través de una API según una programación, en lugar de reaccionar a cada cambio de campo.
Son capas complementarias, no sustitutas. Un estudio que analizó 100 proveedores de API consolidados reveló que el 83 % ofrecía un servicio de webhooks en la investigación de 2023, y un informe posterior mostró que la adopción ascendía al 85 %, tal como se documenta en el estudio State of Webhooks. Los proveedores no están reemplazando las API por webhooks; están añadiendo la entrega de eventos como una capa adicional.
El modelo push también conlleva obligaciones que el modelo pull no exige. Un endpoint de webhook debe verificar firmas, tolerar entregas duplicadas y registrar cada evento para su posterior conciliación, ya que la fuente volverá a enviar los datos tanto si está listo como si no.
Si está enrutando ambos a través de una infraestructura compartida, conviene entender qué es una pasarela de API de la mano de GoReplay, ya que las pasarelas suelen gestionar la autenticación, la limitación de frecuencia y el enrutamiento para el tráfico de la API, mientras que los receptores de webhooks necesitan su propia verificación y gestión de colas previa.
Dibújelo en una pizarra antes de aprobar un diseño. Etiquete al iniciador en cada flecha. Si su equipo no puede precisar quién llama a quién para una conexión a la red WiFi frente a una consulta del historial de estancia, no está listo para evaluar proveedores.
Comparativa entre webhooks y API según los criterios clave
Olvide las listas genéricas de ventajas e inconvenientes. Evalúe ambos patrones en función de la dirección, la latencia, el volumen de solicitudes, el comportamiento ante fallos, la exposición a la seguridad y la gobernanza. El siguiente gráfico presenta visualmente los seis criterios antes de la tabla detallada.
Webhooks frente a API según los criterios de integración
| Criterio | Webhook | API |
|---|---|---|
| Dirección del tráfico | El origen envía datos a tu endpoint cuando ocurre un evento | El cliente solicita datos al origen bajo demanda |
| Latencia | Casi en tiempo real, registrada como inferior a un segundo en la siguiente comparación | Limitada por el intervalo de consulta (polling) |
| Volumen de solicitudes | Solicitudes principalmente cuando se producen cambios | Llamadas repetidas incluso cuando nada ha cambiado |
| Fallos y recuperación | Al menos una vez, reintentos, posibles duplicados | El cliente reintenta en cualquier momento, conciliación más sencilla |
| Exposición de seguridad | Receptor accesible públicamente, posibilidad de mensajes falsificados o de retransmisión | Autenticación y autorización de cada solicitud del cliente |
| Gobernanza | Comprobaciones de firma, registros de solo lectura (append-only), gestión de colas de mensajes fallidos (dead-letter) | Permisos (scopes), límites de frecuencia (rate limits), auditoría de lecturas y escrituras |
Las filas de latencia y volumen son donde el cálculo del sondeo se vuelve implacable. En una comparación representativa en la documentación de Hook0 que compara webhooks frente a sondeo, el sondeo de 60 segundos produce un retraso medio de 30 segundos y aproximadamente 14,4 millones de llamadas a la API al día al realizar comprobaciones una vez por segundo en un escenario de gran volumen. Reducir el sondeo a 5 segundos arroja una media de 2,5 segundos, pero eleva el tráfico a aproximadamente 172,8 millones de llamadas al día, según la misma comparación. Esos datos son cálculos de escenarios, no referencias universales, así que mida la latencia del proveedor, la frecuencia de eventos y los límites de tasa en su propia región. La tendencia sigue siendo clara: no se puede lograr el tiempo real mediante sondeos de forma económica.
Los fallos y la recuperación funcionan en ambas direcciones. La consulta periódica (polling) es sencilla y recuperable. Si una lectura falla, se vuelve a intentar y se reconcilia. Los webhooks exigen el uso de colas, controles de contrapresión y gestión de reintentos porque el emisor decide cuándo llega el tráfico, incluso durante su hora punta de servicio o su ventana de despliegue.
El siguiente recorrido refuerza la diferencia de dirección y tiempo antes de abordar la seguridad.
La exposición a riesgos de seguridad es asimétrica, no se trata de dos versiones del mismo trabajo. La seguridad de las API se centra en autenticar cada solicitud del cliente. La seguridad de los webhooks añade la defensa de un extremo público frente a mensajes falsificados, reproducidos, malformados y duplicados, tal como se explica en la guía de SuprSend sobre la seguridad de webhooks frente a API. Esto implica firmar la solicitud sin procesar, validar la frescura de la marca de tiempo, utilizar la comparación de tiempo constante, aplicar HTTPS y hacer que el procesamiento sea idempotente.
El gobierno del sistema se deriva de eso. Pregúntese si un evento entrante puede modificar de forma segura un registro de invitado o activar un envío en múltiples instalaciones, zonas horarias y reglas de aprobación. Cuando revise las integraciones de Purple Engage o cualquier otro directorio, no se limite a comprobar si aparece un logotipo. Pregunte qué eventos se envían por push, cuáles debe obtener por pull, cómo funcionan los reintentos y cómo probaría que un registro es correcto tras una caída del servicio.
Qué patrón se adapta mejor a cada evento del recinto
Evalúe cada evento con dos preguntas: ¿Con qué rapidez debe reaccionar y cuál es el coste de actuar sobre datos desactualizados o duplicados? La siguiente imagen es un recordatorio útil de que estos eventos comienzan como momentos físicos en un establecimiento, no como filas en una base de datos.
Inicios de sesión WiFi
Utilice un webhook como disparador. Un usuario que acaba de conectarse está en el establecimiento en este momento, por lo que un mensaje de bienvenida, una oferta presencial o una invitación a una encuesta pierden valor con el retraso. Hacer sondeos (polling) para detectar conexiones añade latencia sin ofrecer ningún beneficio.
No permita que la carga útil (payload) cree el registro por sí sola. Conserve el ID del evento y, a continuación, confirme la identidad y el consentimiento antes de incorporar al cliente en un flujo de interacción. Una lectura periódica de la API permite recuperar las conexiones perdidas mientras su receptor estaba fuera de servicio.
Ventas de TPV
Los webhooks se adaptan a las ventas por la misma razón, con un impacto aún mayor. Una transacción cerrada puede activar un recibo, una solicitud de reseña o la actualización de un segmento basado en el gasto mientras la visita aún está reciente. Si está evaluando una caja registradora como la integración de Toast para Purple Engage, compruebe exactamente qué estados de transacción emiten eventos, si los reembolsos y las anulaciones emiten eventos independientes y cómo se muestra una factura pagada parcialmente. Esos detalles importan más que la palabra webhook en una ficha técnica.
El modo de fallo en este punto resulta muy costoso. Los eventos de venta duplicados pueden contabilizar el gasto dos veces, corromper la atribución y emitir ofertas duplicadas. Diseñe controladores idempotentes y considere el registro de la API como la fuente fidedigna para el gasto final.
Reservas
Las reservas necesitan ambos enfoques, inclinándose más hacia la API. Un webhook para una reserva nueva, modificada o cancelada le permite reaccionar rápidamente, confirmar, recordar o activar una etapa de la interacción. Sin embargo, las reservas cambian de estado repetidamente: el tamaño del grupo varía, las horas se modifican o se reciben depósitos.
Un webhook de reserva le indica que eche un vistazo. No debería ser la última palabra sobre el estado actual de la reserva.
Obtenga el estado actual a través de la API antes de enviar cualquier comunicación al cliente. Si actúa sobre una carga útil previa tras haber perdido un webhook de cancelación, le recordará a un cliente una reserva que ya no tiene.
Estancias y salidas de hotel
Las salidas activan encuestas posteriores a la estancia y solicitudes de opinión, por lo que un webhook ofrece una iniciación oportuna. El historial de estancia, los ingresos por habitación y los detalles de la cuenta pertenecen a lecturas de API. Son datos históricos, paginados y sujetos a corrección tras la salida.
Depender únicamente de los webhooks para los registros de estancias es un error clásico. Una sola caída del receptor y estancias completas desaparecerán de la segmentación. Utilice la conciliación programada mediante la API para corregir estas desviaciones y realice cargas retroactivas a través de la API al incorporar un nuevo establecimiento. Purple Engage, en este contexto, combina registros de WiFi, recibos de TPV, reservas y estancias de hotel en un único perfil de cliente, algo que solo funciona si cada fuente dispone tanto de una ruta de activación como de una ruta de recuperación.
Diseño de un receptor que no falle en producción
La fiabilidad no es una función del proveedor que se pueda comprar. Es un conjunto de decisiones que se toman antes de que el primer establecimiento empiece a operar. Diseñe para una entrega al menos una vez (at-least-once delivery), no exactamente una vez, y todo lo demás vendrá dado.
Confirme la recepción rápidamente, procese después
Autentique la solicitud, encole el proceso de forma duradera y devuelva una confirmación de éxito. Considere únicamente una respuesta 2xx como acuse de recibo, tal como se establece en la guía de Svix sobre garantías de entrega de webhooks. No ejecute la segmentación, la emisión de ofertas ni el envío de mensajes dentro del controlador de la solicitud. Los controladores lentos provocan tiempos de espera agotados, lo que genera reintentos y multiplica los registros duplicados.
Una programación documentada utiliza retrasos de 30 segundos, 2 minutos, 15 minutos, 1 hora, 4 horas, 12 horas y 24 horas, para un total de ocho intentos durante aproximadamente 41 horas, con exponenciación posterior y aleatorización (jitter), según las directrices de Svix enlazadas anteriormente. Ese es el margen que debe soportar su diseño. Que un reintento llegue un día después es algo normal, no una anomalía.
Asegúrese de que los duplicados no causen problemas
Guarde el identificador de evento estable del proveedor y utilícelo como clave de idempotencia. Si ya lo ha procesado, confirme la recepción y omita el efecto secundario. Las entregas agotadas van a una cola de mensajes no procesados (dead-letter queue) con soporte de reintento, de modo que un operador pueda inspeccionarlas y volver a procesarlas en lugar de descubrir ausencias a través de quejas de los clientes.
Para los equipos que transmiten eventos a la infraestructura descendente, esta integración de webhook a Kafka sin código de Streamkap es una referencia útil para mover eventos de webhook a Kafka sin necesidad de crear manualmente la capa de ingesta. Elija lo que elija, la cola se sitúa entre la recepción y la lógica empresarial. Eso es fundamental.
Verifique antes de confiar
- Verifique la firma HMAC en el cuerpo sin procesar (raw body): Si analiza primero y vuelve a serializar, romperá firmas válidas o aceptará firmas no válidas.
- Compruebe la actualización de la marca de tiempo: Se debe rechazar una solicitud antigua pero válida que se reproduzca hoy, lo que le protege contra el reenvío de cargas útiles capturadas.
- Compare en tiempo constante: La comparación de cadenas ordinaria puede filtrar información sobre los tiempos de respuesta.
- Autorice por fuente: Una firma de su proveedor de reservas no debería poder escribir eventos con formato de punto de venta (POS).
La estandarización está mejorando. La especificación Open Webhooks converge en identificadores comunes, marcas de tiempo y firmas HMAC-SHA256, y la norma RFC 9421 proporciona un marco estandarizado para firmas de mensajes HTTP. No espere a que se adopte de forma universal. Implemente los controles ahora.
Vuelva a verificar el consentimiento en el último momento
La gobernanza es donde el marketing para establecimientos físicos se desvía de los consejos de integración genéricos. Mantenga registros de auditoría de solo lectura, gestione explícitamente las zonas horarias de los establecimientos, respete los requisitos de procesamiento regionales y vuelva a verificar el consentimiento actual y la elegibilidad inmediatamente antes de realizar cualquier envío o emisión de oferta. Un huésped puede darse de baja entre el evento original y un reintento 12 horas más tarde. Su controlador debe respetar la elección más reciente, no la carga útil anterior.
Por qué la verdadera elección es combinar webhook y API
La comparación real no es webhook frente a API. Es solo webhook frente a webhook más API. Usar solo webhook falla en producción.
Los reintentos crean duplicados. Los eventos llegan desordenados, por lo que una cancelación puede llegar antes que la reserva que cancela. Una breve interrupción crea vacíos que nadie nota hasta que un segmento subestima a los clientes habituales o una campaña se atribuye visitas que no generó. Las métricas de latencia no reflejan nada de eso.
El patrón de coherencia que funciona
- Conserve el ID de evento del proveedor al recibirlo, antes de cualquier procesamiento.
- Haga que cada controlador sea idempotente, de modo que una segunda entrega no altere nada.
- Obtenga el estado actual a través de la API antes de ejecutar cualquier efecto secundario, mensaje, oferta, cambio de segmento o canje.
- Ejecute una conciliación programada con la instantánea de origen para detectar registros faltantes, desordenados o corregidos.
Trate el webhook como un timbre y la API como la acción de comprobar quién está en la puerta. Este enfoque coincide con el artículo sobre webhooks frente a API para desarrolladores de WebinOne, que cubre la elección de implementación desde el punto de vista del desarrollador. Para los equipos del recinto, lo que importa es la consecuencia operativa. El registro de invitados, como la vista unificada descrita en los datos de invitados de Purple Engage, solo es fiable si cada fuente que lo alimenta cuenta con una ruta de recuperación, no solo un activador.
Prueba de diseño: Si su receptor se quedara fuera de línea durante una hora en su sábado de mayor actividad, ¿podría demostrar mañana que cada conexión WiFi, venta, reserva y salida se recuperó exactamente una vez a efectos prácticos? Si no es así, aún no dispone de un diseño híbrido.
Omita la conciliación y los costes se acumularán. Las trayectorias duplicadas molestan a los clientes y malgastan el presupuesto de las ofertas. La segmentación desactualizada se dirige a personas que visitaron el establecimiento ayer como si hubieran dejado de acudir. La atribución exagera el impacto incremental porque las compras se contabilizaron dos veces o no se registraron los momentos de salida. Ninguno de estos problemas aparece como error de integración en un panel de control. Se manifiestan como un marketing que, poco a poco, deja de ser creíble.
Desarrolle el modelo híbrido desde el principio. Resulta menos deslumbrante que una demostración en tiempo real, pero marca la diferencia entre una integración que resiste un despliegue multiubicación y una en la que su equipo deja de confiar. Elija webhooks para señales de baja latencia, API para el estado fidedigno y la recuperación, y no implemente ninguno de los dos de forma aislada para nada que pueda enviar un mensaje o emitir una oferta.
Si está planificando un despliegue multisede y desea que el WiFi, los TPV, las reservas y las estancias alimenten un único registro de cliente con webhooks firmados, una API pública y la comprobación del consentimiento antes de cada envío, explore Purple Engage y revise sus integraciones frente a la lista de verificación híbrida anterior. Aporte su evento más complejo, como la venta en TPV o el pago que no pueda permitirse duplicar, y compruebe si el diseño lo recupera tras una caída del servicio.