Support Hub/API & Integrations/Webhook e polling a confronto: come arrivano i dati…
Translated from the English article and reviewed by a person. Read the English original
Developer

Webhook e polling a confronto: come arrivano i dati biometrici in tempo reale al tuo server

Webhook e polling a confronto: come arrivano i dati biometrici in tempo reale al tuo server

Ogni integrazione biometrica deve rispondere a una domanda fondamentale: come fa una timbratura alla porta a diventare un record nel tuo sistema? Ci sono due modi. Il tuo server può continuare a chiedere al dispositivo se è successo qualcosa di nuovo, ed è il polling. Oppure il sistema può comunicare al tuo server nel momento esatto in cui accade qualcosa, ed è un webhook. Per i dati di presenza e accesso biometrici, la scelta tra webhook e polling influisce sulla freschezza dei dati, sul carico che viene scaricato su dispositivi e reti e sull'affidabilità dei record. Questa guida spiega entrambi gli approcci in termini semplici, mostra perché i webhook sono l'opzione predefinita migliore per i dati biometrici, illustra come costruire un ricevitore webhook affidabile e spiega dove il polling mantiene ancora una sua utilità.

01 · Pull vs Push

Due modi in cui i dati possono viaggiare

Immagina di aspettare un pacco importante. Potresti andare alla porta d'ingresso ogni cinque minuti per controllare se è arrivato. Oppure potresti aspettare che suoni il campanello. In entrambi i casi il pacco arriva. Nel primo caso, però, fai molti viaggi inutili e ricevi comunque il pacco fino a cinque minuti in ritardo. Nel secondo, sai che è arrivato nel momento esatto in cui arriva.

Questa è la differenza tra polling e webhook.

Polling: il tuo server continua a chiedere

Il tuo server

Chiede: ci sono nuove timbrature dall'ultima volta?

→

Dispositivo o sistema

Risponde: niente di nuovo

→

Attesa

Pausa per l'intervallo di polling

→

Ripetizione

Chiede di nuovo, ancora e ancora, tutto il giorno

Webhook: il sistema comunica al tuo server

Timbratura del dipendente

Un'impronta digitale, un volto o una scheda verificati

→

Gateway

Invia l'evento immediatamente al tuo URL webhook

→

Il tuo server

Riceve l'evento e risponde completato

→

Completato

Nessuna attesa e nessuna richiesta sprecata

Polling Webhook
Chi avvia la comunicazione Il tuo server Il sistema che possiede i dati
Quando arrivano i dati Alla successiva interrogazione, con un ritardo fino a un intero intervallo Immediatamente dopo la timbratura
Richieste quando non succede nulla Continue, per lo più vuote Nessuna
Carico su dispositivi e rete Costante, indipendentemente dall'attività Solo quando c'è qualcosa da inviare
Complessità per te Tenere traccia di ciò che hai già recuperato Ricevere e confermare gli eventi

02 · I costi nascosti

Perché il polling fatica con i dati biometrici

Il polling funziona per i dati che cambiano lentamente o per cui un ritardo non conta. I dati biometrici di presenza e accesso sono l'opposto. Vengono generati in forti picchi all'inizio e alla fine dei turni, restano silenziosi per gran parte del resto del tempo e spesso servono subito.

Il ritardo è intrinseco

Con il polling, il ritardo nel caso peggiore è sempre uguale al tuo intervallo di polling. Una timbratura avvenuta un secondo dopo un'interrogazione attende l'intero intervallo prima che il tuo server la veda.

Intervallo di polling Ritardo massimo prima che il sistema lo sappia Adatto per
Ogni 24 ore Fino a un intero giorno Solo per le buste paga mensili
Ogni ora Fino a 60 minuti Report giornalieri
Ogni 5 minuti Fino a 5 minuti La maggior parte delle dashboard, non gli avvisi
Ogni minuto Fino a 60 secondi Quasi in tempo reale, con un alto costo di richieste
Webhook Nessun ritardo di polling Dashboard live, notifiche e automazioni

La maggior parte delle richieste è sprecata

Per avvicinarsi al tempo reale, bisogna interrogare più spesso. Ma la maggior parte di quelle richieste non restituisce nulla. Interrogare un dispositivo ogni minuto significa 1.440 richieste per dispositivo al giorno. Su 50 dispositivi, sono 72.000 richieste al giorno, la maggior parte delle quali pone una domanda la cui risposta è “nessuna novità.” Ognuna di queste richieste utilizza capacità di rete e tempo di elaborazione del dispositivo.

Tenere traccia diventa fragile

Un'integrazione basata sul polling deve ricordare ciò che ha già recuperato, di solito memorizzando l'ora o la posizione dell'ultimo record letto. Se questo riferimento è sbagliato, a causa di un riavvio, di una differenza di orologio tra server e dispositivo o di record memorizzati mentre un dispositivo era offline, l'integrazione o perde delle timbrature o le importa due volte. Questi problemi sono silenziosi e spesso emergono solo durante una contestazione sulla busta paga.

Diventa più difficile con ogni sede

Con un solo dispositivo, il polling è gestibile. Con decine di dispositivi distribuiti su più sedi e marchi, ciascuno con la propria connessione, il proprio intervallo e il proprio riferimento dell'ultimo dato letto, il polling diventa un compito a sé di pianificazione e monitoraggio.

Il polling pone la stessa domanda migliaia di volte al giorno per cogliere i pochi momenti che contano. I webhook parlano solo quando è successo davvero qualcosa.

03 · Consegna push con Cams

Come funzionano i webhook biometrici

Con Cams Biometrics Gateway, la consegna tramite webhook si chiama Callback API. Fornisci al Gateway un URL sul tuo server e ogni timbratura verificata viene inviata a quell'URL nel momento in cui avviene. Gli eventi di callback vengono consegnati con latenza zero per i dispositivi su Native Push.

Cosa riceve il tuo server

Callback API, richiesta inviata al tuo URL webhook dal 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 Cosa comunica al tuo server
OperationID Un riferimento univoco per questo evento
LabelName Il nome della sede o della porta a cui è assegnato il dispositivo
SerialNumber Il dispositivo specifico che ha registrato la timbratura
Type Se si tratta di un ingresso o di un'uscita
InputType Come la persona si è verificata: impronta digitale, volto, scheda, PIN e così via
UserId Chi ha timbrato, corrispondente all'ID nel tuo sistema HR
LogTime Quando è avvenuta la timbratura sul dispositivo, con lo scostamento del fuso orario
AuthToken Il token che il tuo server usa per confermare che la richiesta è autentica
Time La data e ora del messaggio stesso, in GMT

Cosa deve restituire il tuo server

Una volta ricevuto l'evento, il tuo server risponde con una breve conferma. Questo comunica al Gateway che l'evento è arrivato correttamente.

Callback API, risposta che il tuo webhook deve restituire

{ "status": "done" }

Push, anche quando il dispositivo non può

Non tutti i dispositivi possono inviare dati autonomamente. Alcuni dispositivi meno recenti o non verificati memorizzano le presenze solo in un database locale o in un file. Con Cams Hybrid Push, il Gateway può leggere da quel database (DB Pull) oppure monitorare quel file (File Processing), e comunque consegnare i nuovi record di presenza al tuo Callback URL. Il tuo server riceve la consegna push in entrambi i casi, anche se il dispositivo sottostante normalmente dovrebbe essere interrogato.

04 · Buone pratiche

Costruire un ricevitore webhook affidabile

Un ricevitore webhook è semplice da costruire, ma alcune pratiche fanno la differenza tra uno che funziona nei test e uno che funziona ogni giorno per anni.

Pratica Cosa fare Perché è importante
Conferma per prima cosa Rispondi con lo stato done non appena l'evento è ricevuto, poi esegui le operazioni più lente Mantiene breve la richiesta del Gateway, anche se i tuoi sistemi a valle sono lenti
Metti il lavoro in coda Inserisci ogni evento ricevuto in una coda o in una tabella ed elaboralo separatamente Gestisce i picchi di inizio turno senza perdere eventi
Valida l'AuthToken Controlla il token in ogni richiesta prima di fidarti dei dati Impedisce a chiunque altro di inviare presenze false al tuo URL
Usa HTTPS Esponi il tuo webhook solo tramite HTTPS, con la cifratura AES-256 opzionale dal Gateway I dati di presenza sono dati personali e devono essere protetti durante la trasmissione
Rendilo idempotente Usa OperationID per rilevare e ignorare gli eventi già elaborati Una consegna ripetuta non diventa mai un record di presenza duplicato
Usa LogTime per le presenze Registra le presenze usando LogTime, non l'ora in cui il tuo server ha ricevuto l'evento Gli eventi memorizzati durante un'interruzione arrivano in ritardo ma conservano il loro vero orario di timbratura
Ordina per LogTime Ordina gli eventi per LogTime prima di calcolare le ore Gli eventi bufferizzati possono arrivare fuori ordine dopo una caduta di connessione
Registra tutto Conserva una traccia di ogni evento ricevuto e di ogni risposta inviata Rende semplici la risoluzione dei problemi e i controlli

Pianifica per i picchi, non per le medie

Una sede con 300 dipendenti può ricevere quasi nulla per gran parte della giornata, poi 300 eventi in dieci minuti al cambio turno. Progetta il tuo ricevitore per quel picco. Confermare rapidamente e mettere il lavoro in coda è il modo più semplice per gestirlo.

Dove può trovarsi il webhook

Il tuo webhook necessita di un indirizzo HTTPS pubblico raggiungibile dal Gateway. Può trattarsi di un endpoint nella tua applicazione, di una piccola cloud function o di un webhook in entrata in uno strumento di automazione come n8n o Make. I tuoi dispositivi, invece, non hanno bisogno di un IP pubblico. Le sedi dietro firewall possono connettersi al Gateway tramite l'Hybrid Connector, che funziona con una connessione in uscita.

Il tuo sistema decide cosa succede dopo

Il Gateway consegna gli eventi verificati e attende la tua conferma. Cosa accade dopo, come scrivere nel tuo HRMS, aggiornare una dashboard, inviare un avviso di ritardo o avviare un flusso di lavoro, è deciso dal tuo software e dalle tue regole.

05 · Usare entrambi insieme

Dove il polling mantiene ancora un ruolo

I webhook dovrebbero essere l'opzione predefinita per i dati biometrici in tempo reale. Ma recuperare i dati su richiesta ha ancora compiti utili e specifici. Le integrazioni più solide usano i webhook per la consegna in tempo reale e recuperi on demand occasionali per verifiche e ripristino.

Situazione Approccio migliore Perché
Presenze in tempo reale, dashboard, notifiche Webhook (Callback API) I dati arrivano nel momento in cui avviene una timbratura
Il tuo server è stato offline per un periodo Recupera i log su richiesta Colma ogni lacuna e conferma che non sia sfuggito nulla
Riconciliazione notturna o settimanale Recupera i log secondo una pianificazione Confronta con ciò che i webhook hanno consegnato, come rete di sicurezza
Configurazione di una nuova integrazione Recupera i log storici una volta Importa lo storico esistente prima che subentrino i webhook
Controllo di un periodo specifico Recupera i log per quel periodo Produce una registrazione completa da esaminare

Per questi compiti, la Cams RESTful API include operazioni per caricare i log dai dispositivi. Usato occasionalmente e con uno scopo preciso, il recupero dei log integra i webhook invece di farli concorrenza. La differenza sta nell'intento: recuperi i log quando hai un motivo preciso, invece di chiedere ogni minuto per precauzione.

Domande frequenti

Il polling è mai migliore dei webhook per i dati biometrici?

Il polling può essere più semplice quando il tuo sistema non può esporre alcun endpoint pubblico, oppure per importazioni storiche una tantum. Per i dati di presenza e accesso in corso, i webhook sono più veloci, più leggeri per dispositivi e reti e più facili da scalare su più sedi.

Cosa succede alle timbrature se il mio server webhook è non disponibile?

Se il tuo server webhook è non disponibile, i dati di presenza vengono memorizzati nella coda di Cams. Quando il tuo server torna online, i record in coda vengono inviati automaticamente al tuo server. La coda si riavvia automaticamente ogni 3 ore, e puoi anche riavviarla manualmente in qualsiasi momento dal Cams Portal. Questo garantisce che i record di presenza non vadano persi a causa di un'interruzione temporanea del server.

I miei dispositivi biometrici hanno bisogno di un IP pubblico perché i webhook funzionino?

No. Il tuo URL webhook deve essere raggiungibile dal Gateway, ma i tuoi dispositivi no. Le sedi senza IP pubblico possono connettersi tramite l'Hybrid Connector, che usa una connessione in uscita.

Posso ricevere webhook in n8n, Make o Zapier?

Sì. Qualsiasi strumento in grado di ricevere un webhook in entrata può ricevere gli eventi Cams Callback. n8n e Make possono anche restituire direttamente la conferma done richiesta. Zapier potrebbe richiedere un piccolo relay davanti a sé per inviare quella risposta.

Perché LogTime e Time sono diversi nel payload?

LogTime è il momento in cui la persona ha effettivamente timbrato, registrato con lo scostamento del fuso orario del dispositivo. Time è la data e ora del messaggio stesso, in GMT. Se un dispositivo era offline, il messaggio può essere inviato molto tempo dopo la timbratura. Per le presenze usa sempre LogTime.

Conclusione: lascia suonare il campanello

Il polling aveva senso quando i dispositivi biometrici potevano essere letti solo su richiesta e nessuno si aspettava che i dati di presenza fossero in tempo reale. Oggi dashboard HR, sistemi paghe, strumenti di automazione e assistenti AI funzionano al meglio con i dati nel momento stesso in cui esistono. Porre a un dispositivo la stessa domanda migliaia di volte al giorno è un modo lento e dispendioso per arrivarci.

I webhook trasformano ogni timbratura verificata in un evento che i tuoi sistemi ricevono immediatamente, senza richieste sprecate e senza un fragile tracciamento di ciò che è già stato recuperato. Riserva il recupero dei log su richiesta a ciò che fa meglio, colmare le lacune e verificare la completezza, e lascia che siano i webhook a gestire tutto il resto.

Cams Biometrics Gateway è costruito attorno alla consegna push. La sua Callback API invia ogni timbratura verificata al tuo webhook in tempo reale, da dispositivi di oltre 15 marchi, in un unico formato JSON coerente. Le modalità Hybrid Push consegnano eventi push anche da dispositivi che non possono inviare dati autonomamente, e la RESTful API fornisce operazioni on demand come il caricamento dei log per la riconciliazione. Tutte le comunicazioni avvengono tramite HTTP/HTTPS con validazione del token di autenticazione e cifratura AES-256 opzionale. Scopri la piattaforma su CamsBiometrics.com e leggi la documentazione completa della Callback API su developer.camsbiometrics.com.

Was this article helpful?