Support Hub/API & Integrations/Webhooks vs. polling: cómo deben llegar los datos…
Translated from the English article and reviewed by a person. Read the English original
Developer

Webhooks vs. polling: cómo deben llegar los datos biométricos en tiempo real a tu servidor

Webhooks vs. polling: cómo deben llegar los datos biométricos en tiempo real a tu servidor

Cada integración biométrica debe responder a una pregunta básica: ¿cómo pasa un escaneo en la puerta a convertirse en un registro en tu sistema? Hay dos formas de hacerlo. Tu servidor puede preguntar continuamente al dispositivo si ha ocurrido algo nuevo, lo que se llama polling. O el sistema puede avisar a tu servidor en el momento en que ocurre algo, lo que es un webhook. En los datos de asistencia y acceso biométricos, la elección entre webhooks y polling afecta a la actualidad de tus datos, a la carga que generas en los dispositivos y las redes, y a la fiabilidad de tus registros. Esta guía explica ambos enfoques en términos sencillos, muestra por qué los webhooks son la opción predeterminada más adecuada para los datos biométricos, explica cómo crear un receptor de webhooks fiable y detalla en qué casos el polling sigue teniendo sentido.

01 · Pull frente a Push

Dos formas en que los datos pueden viajar

Imagina que esperas un paquete importante. Podrías ir a la puerta principal cada cinco minutos para comprobar si ha llegado. O podrías esperar a que suene el timbre. Ambas opciones te dan el paquete. La primera te obliga a hacer muchos viajes y aun así puedes llegar con hasta cinco minutos de retraso. La segunda te avisa en el momento en que llega.

Esa es la diferencia entre polling y webhooks.

Polling: tu servidor sigue preguntando

Tu servidor

Pregunta: ¿hay escaneos nuevos desde la última vez?

→

Dispositivo o sistema

Responde: nada nuevo

→

Espera

Espera el intervalo de polling

→

Repite

Pregunta de nuevo, una y otra vez, todo el día

Webhook: el sistema avisa a tu servidor

El empleado escanea

Un escaneo verificado de huella, rostro o tarjeta

→

Gateway

Envía el evento de inmediato a tu URL de webhook

→

Tu servidor

Recibe el evento y responde done

→

Hecho

Sin esperas y sin solicitudes desperdiciadas

Polling Webhooks
Quién inicia la conversación Tu servidor El sistema que tiene los datos
Cuándo llegan los datos En la siguiente consulta, con hasta un intervalo completo de retraso Inmediatamente después del escaneo
Solicitudes cuando no pasa nada Continuas, la mayoría vacías Ninguna
Carga en dispositivos y red Constante, sin importar la actividad Solo cuando hay algo que enviar
Complejidad para ti Llevar el control de lo que ya has obtenido Recibir y confirmar los eventos

02 · Los costes ocultos

Por qué el polling tiene problemas con los datos biométricos

El polling funciona con datos que cambian lentamente o cuando un retraso no importa. Los datos de asistencia y acceso biométricos son justo lo contrario. Se generan en ráfagas intensas al inicio y al final de los turnos, están tranquilos durante la mayor parte del resto del tiempo y, con frecuencia, se necesitan de inmediato.

El retraso forma parte del diseño

Con polling, el retraso en el peor de los casos siempre equivale a tu intervalo de polling. Un escaneo que ocurre un segundo después de una consulta espera el intervalo completo antes de que tu servidor lo vea.

Intervalo de polling Retraso en el peor caso antes de que tu sistema lo sepa Suficiente para
Cada 24 horas Hasta un día completo Solo nóminas mensuales
Cada hora Hasta 60 minutos Informes diarios
Cada 5 minutos Hasta 5 minutos La mayoría de los paneles, no las alertas
Cada minuto Hasta 60 segundos Casi en tiempo real, con un alto coste de solicitudes
Webhook Sin retraso por polling Paneles en vivo, notificaciones y automatizaciones

La mayoría de las solicitudes se desperdician

Para acercarte al tiempo real, consultas con más frecuencia. Pero la mayoría de esas solicitudes no devuelven nada. Consultar un dispositivo cada minuto significa 1.440 solicitudes por dispositivo al día. En 50 dispositivos, son 72.000 solicitudes al día, la mayoría de ellas para hacer una pregunta cuya respuesta es “nada nuevo”. Cada una de esas solicitudes consume capacidad de red y tiempo de procesamiento del dispositivo.

Llevar el control se vuelve frágil

Una integración por polling debe recordar lo que ya ha obtenido, normalmente guardando la hora o la posición del último registro visto. Si ese marcador es incorrecto, por un reinicio, una diferencia de reloj entre el servidor y el dispositivo, o registros almacenados mientras un dispositivo estaba desconectado, la integración pierde escaneos o los importa dos veces. Estos problemas son silenciosos y, a menudo, solo salen a la luz durante una disputa de nómina.

Se complica con cada sede

Con un solo dispositivo, el polling es manejable. Con decenas de dispositivos en varias sedes y marcas, cada uno con su propia conexión, su propio intervalo y su propio marcador del último registro obtenido, el polling se convierte en una tarea de programación y monitorización por sí misma.

El polling hace la misma pregunta miles de veces al día para captar los pocos momentos que importan. Los webhooks solo hablan cuando realmente ha ocurrido algo.

03 · Entrega push con Cams

Cómo funcionan los webhooks biométricos

Con Cams Biometrics Gateway, la entrega por webhook se denomina Callback API. Indicas al Gateway una URL de tu servidor, y cada escaneo verificado se envía a esa URL en el momento en que ocurre. Los eventos de Callback se entregan sin latencia en los dispositivos con Native Push.

Lo que recibe tu servidor

Callback API, solicitud enviada a tu URL de webhook por el Gateway

{
  "RealTime": {
    "OperationID": "9nu1wak5616p",
    "LabelName": "Burj Khalifa",
    "SerialNumber": "ZHM11xxxxxxxx",
    "PunchLog": {
      "Type": "CheckOut",
      "Temperature": "36.8",
      "FaceMask": false,
      "InputType": "Fingerprint",
      "UserId": "2",
      "LogTime": "2020-09-17 07:48:22 GMT +0530"
    },
    "AuthToken": "COJJ7eiIPBGUfmIQPvh2PJWWDLX7OuKs",
    "Time": "2020-09-17 04:19:03 GMT +0000"
  }
}
Campo Lo que indica a tu servidor
OperationID Una referencia única para este evento
LabelName El nombre de la sede o puerta a la que está asignado el dispositivo
SerialNumber El dispositivo concreto que registró el escaneo
Type Si fue una entrada o una salida
InputType Cómo se verificó la persona: huella, rostro, tarjeta, PIN, etc.
UserId Quién escaneó, coincidiendo con el ID de tu sistema de RRHH
LogTime Cuándo ocurrió el escaneo en el dispositivo, con su desfase de zona horaria
AuthToken El token que tu servidor usa para confirmar que la solicitud es auténtica
Time La marca de tiempo del propio mensaje, en GMT

Lo que tu servidor debe devolver

Una vez que tu servidor ha recibido el evento, responde con un acuse de recibo breve. Esto indica al Gateway que el evento llegó correctamente.

Callback API, respuesta que debe devolver tu webhook

{ "status": "done" }

Push, incluso cuando el dispositivo no puede

No todos los dispositivos pueden enviar datos por sí mismos. Algunos dispositivos antiguos o no verificados solo almacenan la asistencia en una base de datos local o en un archivo. Con Cams Hybrid Push, el Gateway puede leer esa base de datos (DB Pull) o vigilar ese archivo (File Processing), y seguir entregando los nuevos registros de asistencia a tu URL de Callback. Tu servidor recibe entrega push en cualquier caso, aunque el dispositivo subyacente normalmente necesitaría ser consultado.

04 · Mejores prácticas

Cómo crear un receptor de webhooks fiable

Un receptor de webhooks es sencillo de construir, pero algunas prácticas marcan la diferencia entre uno que funciona en pruebas y otro que funciona todos los días durante años.

Práctica Qué hacer Por qué importa
Confirmar primero Responde con el estado done en cuanto se reciba el evento y haz el trabajo más lento después Mantiene breve la solicitud del Gateway, incluso si tus sistemas posteriores son lentos
Poner el trabajo en cola Coloca cada evento recibido en una cola o en una tabla y procésalo por separado Gestiona las ráfagas al inicio de turno sin perder eventos
Validar el AuthToken Comprueba el token en cada solicitud antes de confiar en los datos Evita que otros envíen asistencias falsas a tu URL
Usar HTTPS Expón tu webhook solo por HTTPS, con cifrado AES-256 opcional desde el Gateway Los datos de asistencia son datos personales y deben protegerse durante la transmisión
Hacerlo idempotente Usa OperationID para detectar e ignorar eventos que ya has procesado Una entrega repetida nunca se convierte en un registro de asistencia duplicado
Confiar en LogTime para la asistencia Registra la asistencia con LogTime, no con la hora en que tu servidor recibió el evento Los eventos almacenados durante una interrupción llegan más tarde, pero conservan su hora real de escaneo
Ordenar por LogTime Ordena los eventos por LogTime antes de calcular las horas Los eventos almacenados pueden llegar desordenados tras una caída de conexión
Registrar todo Guarda un registro de cada evento recibido y de cada respuesta enviada Facilita la resolución de incidencias y las auditorías

Planifica para las ráfagas, no para los promedios

Una sede con 300 empleados puede no recibir casi nada durante la mayor parte del día y, luego, 300 eventos en diez minutos durante el cambio de turno. Diseña tu receptor para ese pico. Confirmar rápidamente y poner el trabajo en cola es la forma más sencilla de gestionarlo.

Dónde puede alojarse el webhook

Tu webhook necesita una dirección HTTPS pública a la que el Gateway pueda acceder. Puede ser un endpoint de tu propia aplicación, una pequeña función en la nube o un webhook entrante en una herramienta de automatización como n8n o Make. Tus dispositivos no necesitan una IP pública. Las sedes detrás de cortafuegos pueden conectarse al Gateway a través del Hybrid Connector, que funciona mediante una conexión saliente.

Tu sistema decide qué pasa después

El Gateway entrega los eventos verificados y espera tu confirmación. Lo que ocurre después, como escribir en tu HRMS, actualizar un panel, enviar un aviso de llegada tarde o iniciar un flujo de trabajo, lo deciden tu propio software y tus reglas.

05 · Usar ambos juntos

Dónde sigue teniendo sentido el polling

Los webhooks deben ser la opción predeterminada para los datos biométricos en vivo. Pero obtener datos bajo demanda sigue teniendo funciones útiles y concretas. Las integraciones más sólidas usan webhooks para la entrega en tiempo real y consultas puntuales a demanda para verificar y recuperar datos.

Situación Mejor enfoque Por qué
Asistencia en vivo, paneles, notificaciones Webhooks (Callback API) Los datos llegan en el momento en que se produce un escaneo
Tu servidor estuvo fuera de servicio durante un tiempo Obtener los registros bajo demanda Cubre cualquier hueco y confirma que no se perdió nada
Conciliación nocturna o semanal Obtener los registros según un calendario Compara con lo que entregaron los webhooks, como red de seguridad
Configurar una nueva integración Obtener los registros históricos una vez Importa el historial existente antes de que los webhooks tomen el relevo
Auditar un periodo concreto Obtener los registros de ese periodo Genera un registro completo para su revisión

Para estas tareas, la Cams RESTful API incluye operaciones para cargar registros desde los dispositivos. Usada de forma ocasional y con un propósito claro, la obtención de registros complementa a los webhooks en lugar de competir con ellos. La diferencia está en la intención: obtienes los registros cuando tienes un motivo, en lugar de preguntar cada minuto por si acaso.

Preguntas frecuentes

¿El polling es alguna vez mejor que los webhooks para datos biométricos?

El polling puede ser más sencillo cuando tu sistema no puede exponer ningún endpoint público, o para importaciones históricas puntuales. Para los datos de asistencia y acceso continuos, los webhooks son más rápidos, consumen menos recursos de dispositivos y redes, y son más fáciles de escalar entre sedes.

¿Qué pasa con los escaneos si mi servidor de webhooks está caído?

Si tu servidor de webhooks está caído, los datos de asistencia se almacenarán en la cola de Cams. Cuando tu servidor vuelva a estar en línea, los registros en cola se enviarán automáticamente a tu servidor. La cola se reinicia automáticamente una vez cada 3 horas, y también puedes reiniciarla manualmente en cualquier momento desde el Cams Portal. Esto garantiza que los registros de asistencia no se pierdan por una caída temporal del servidor.

¿Mis dispositivos biométricos necesitan una IP pública para que funcionen los webhooks?

No. Tu URL de webhook debe ser accesible para el Gateway, pero tus dispositivos no. Las sedes sin IP pública pueden conectarse a través del Hybrid Connector, que utiliza una conexión saliente.

¿Puedo recibir webhooks en n8n, Make o Zapier?

Sí. Cualquier herramienta que pueda recibir un webhook entrante puede recibir eventos de Cams Callback. n8n y Make también pueden devolver directamente el acuse de recibo done requerido. Zapier puede necesitar un pequeño relé delante para enviar esa respuesta.

¿Por qué LogTime y Time son diferentes en el payload?

LogTime es el momento en que la persona escaneó realmente, registrado con el desfase de zona horaria del dispositivo. Time es la marca de tiempo del propio mensaje, en GMT. Si un dispositivo estaba desconectado, el mensaje puede enviarse mucho después del escaneo. Usa siempre LogTime para la asistencia.

Conclusión: deja que suene el timbre

El polling tenía sentido cuando los dispositivos biométricos solo podían leerse bajo demanda y nadie esperaba que los datos de asistencia fueran en vivo. Hoy, los paneles de RRHH, los sistemas de nóminas, las herramientas de automatización y los asistentes de IA funcionan mejor con los datos en el momento en que existen. Preguntarle a un dispositivo la misma cosa miles de veces al día es una forma lenta y desperdiciadora de llegar hasta ahí.

Los webhooks convierten cada escaneo verificado en un evento que tus sistemas reciben de inmediato, sin solicitudes desperdiciadas y sin el frágil seguimiento de lo que ya se obtuvo. Reserva la obtención de registros bajo demanda para lo que mejor hace, cubrir huecos y comprobar que esté todo completo, y deja que los webhooks transporten todo lo demás.

Cams Biometrics Gateway está diseñado en torno a la entrega push. Su Callback API envía cada escaneo verificado a tu webhook en tiempo real, desde dispositivos de más de 15 marcas, en un único formato JSON coherente. Los modos Hybrid Push entregan eventos push incluso desde dispositivos que no pueden enviar datos por sí mismos, y la RESTful API proporciona operaciones bajo demanda, como la carga de registros para la conciliación. Toda la comunicación se realiza mediante HTTP/HTTPS, con validación de token de autenticación y cifrado AES-256 opcional. Explora la plataforma en CamsBiometrics.com y consulta la documentación completa de la Callback API en developer.camsbiometrics.com.

Was this article helpful?