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.