Webhooks vs Polling: Como os Dados Biométricos em Tempo Real Devem Chegar ao Seu Servidor
Toda integração biométrica precisa responder a uma pergunta básica: como uma marcação feita na porta se torna um registro no seu sistema? Existem duas formas de fazer isso. Seu servidor pode perguntar continuamente ao dispositivo se algo novo aconteceu, o que é o polling. Ou o sistema pode informar seu servidor no momento em que algo acontece, o que é um webhook. Para dados de presença e controle de acesso biométrico, a escolha entre webhooks e polling afeta o quão atualizados estão seus dados, a carga que você impõe aos dispositivos e às redes e a confiabilidade dos seus registros. Este guia explica as duas abordagens em termos simples, mostra por que os webhooks são a melhor opção padrão para dados biométricos, explica como criar um receptor de webhook confiável e mostra onde o polling ainda tem seu lugar.
01 · Pull vs Push
Duas Formas de os Dados Trafegarem
Imagine que você está esperando uma encomenda importante. Você poderia ir até a porta da frente a cada cinco minutos para verificar se ela chegou. Ou poderia esperar a campainha tocar. Ambas as opções fazem a encomenda chegar até você. Uma desperdiça muitas idas e ainda deixa você com até cinco minutos de atraso. A outra avisa no momento exato em que ela chega.
Essa é a diferença entre polling e webhooks.
Polling: seu servidor continua perguntando
|
Seu servidor Pergunta: há novas marcações desde a última vez? |
→ |
Dispositivo ou sistema Responde: nada de novo |
→ |
Aguardar Esperar pelo intervalo de polling |
→ |
Repetir Perguntar de novo, e de novo, o dia todo |
Webhook: o sistema avisa seu servidor
|
Marcação do funcionário Uma leitura verificada de impressão digital, rosto ou cartão |
→ |
Gateway Envia o evento para sua URL de webhook imediatamente |
→ |
Seu servidor Recebe o evento e responde concluído |
→ |
Concluído Sem espera e sem requisições desperdiçadas |
| Polling | Webhooks | |
|---|---|---|
| Quem inicia a conversa | Seu servidor | O sistema que possui os dados |
| Quando os dados chegam | Na próxima consulta, com até um intervalo completo de atraso | Imediatamente após a marcação |
| Requisições quando nada acontece | Contínuas, a maioria vazia | Nenhuma |
| Carga nos dispositivos e na rede | Constante, independentemente da atividade | Somente quando há algo para enviar |
| Complexidade para você | Controlar o que já foi buscado | Receber e confirmar os eventos |
02 · Os Custos Ocultos
Por Que o Polling Tem Dificuldades com Dados Biométricos
O polling funciona para dados que mudam lentamente ou em que um atraso não faz diferença. Os dados de presença e controle de acesso biométrico são o oposto. Eles são gerados em rajadas intensas no início e no fim dos turnos, ficam praticamente parados na maior parte do tempo e costumam ser necessários imediatamente.
O atraso é inerente ao modelo
No polling, o atraso no pior caso sempre é igual ao seu intervalo de polling. Uma marcação feita um segundo depois de uma consulta espera o intervalo inteiro até que seu servidor a veja.
| Intervalo de polling | Atraso no pior caso até o sistema saber | Adequado para |
|---|---|---|
| A cada 24 horas | Até um dia inteiro | Apenas folha de pagamento mensal |
| A cada hora | Até 60 minutos | Relatórios diários |
| A cada 5 minutos | Até 5 minutos | A maioria dos painéis, mas não alertas |
| A cada minuto | Até 60 segundos | Próximo do tempo real, com alto custo de requisições |
| Webhook | Sem atraso de polling | Painéis ao vivo, notificações e automações |
A maioria das requisições é desperdiçada
Para se aproximar do tempo real, você consulta com mais frequência. Mas a maioria dessas requisições não retorna nada. Consultar um dispositivo a cada minuto significa 1.440 requisições por dispositivo por dia. Em 50 dispositivos, são 72.000 requisições por dia, a maioria delas fazendo uma pergunta cuja resposta é “nada de novo”. Cada uma dessas requisições consome capacidade de rede e tempo de processamento do dispositivo.
Controlar o que já foi lido fica frágil
Uma integração por polling precisa lembrar o que já buscou, geralmente armazenando o horário ou a posição do último registro visto. Se esse marcador estiver errado, por causa de uma reinicialização, de uma diferença de relógio entre servidor e dispositivo ou de registros armazenados enquanto um dispositivo estava offline, a integração ou perde marcações ou as importa duas vezes. Esses problemas são silenciosos e, muitas vezes, só aparecem durante uma disputa sobre a folha de pagamento.
Fica mais difícil a cada unidade
Com um único dispositivo, o polling é fácil de gerenciar. Com dezenas de dispositivos em várias unidades e marcas, cada um com sua própria conexão, seu próprio intervalo e seu próprio marcador do último registro buscado, o polling se transforma em uma tarefa própria de agendamento e monitoramento.
|
O polling faz a mesma pergunta milhares de vezes por dia para captar os poucos momentos que importam. Os webhooks só falam quando algo realmente aconteceu. |
03 · Entrega Push com a Cams
Como Funcionam os Webhooks Biométricos
Com o Cams Biometrics Gateway, a entrega por webhook é chamada de Callback API. Você informa ao Gateway uma URL no seu servidor, e cada marcação verificada é enviada a essa URL no momento em que acontece. Os eventos de callback são entregues sem latência para dispositivos com Native Push.
O que seu servidor recebe
|
Callback API, requisição enviada à sua URL de webhook pelo 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 | O que informa ao seu servidor |
|---|---|
| OperationID | Uma referência única para este evento |
| LabelName | O nome da unidade ou da porta à qual o dispositivo está atribuído |
| SerialNumber | O dispositivo específico que registrou a marcação |
| Type | Se foi uma entrada ou uma saída |
| InputType | Como a pessoa foi verificada: impressão digital, rosto, cartão, PIN e assim por diante |
| UserId | Quem registrou a marcação, correspondendo ao ID no seu sistema de RH |
| LogTime | Quando a marcação ocorreu no dispositivo, com o deslocamento do fuso horário |
| AuthToken | O token que seu servidor usa para confirmar que a requisição é genuína |
| Time | A data e hora da própria mensagem, em GMT |
O que seu servidor deve devolver
Assim que seu servidor recebe o evento, ele responde com uma confirmação curta. Isso informa ao Gateway que o evento chegou com segurança.
|
Callback API, resposta que seu webhook deve retornar { "status": "done" }
|
|
Push, mesmo quando o dispositivo não consegue Nem todo dispositivo consegue enviar dados por conta própria. Alguns dispositivos mais antigos ou não verificados apenas armazenam as marcações em um banco de dados local ou em um arquivo. Com o Cams Hybrid Push, o Gateway pode ler esse banco de dados (DB Pull) ou monitorar esse arquivo (File Processing) e, ainda assim, entregar os novos registros de presença à sua Callback URL. Seu servidor recebe entrega push de qualquer forma, mesmo que o dispositivo subjacente normalmente precisasse ser consultado. |
04 · Boas Práticas
Como Criar um Receptor de Webhook Confiável
Um receptor de webhook é simples de construir, mas algumas práticas fazem a diferença entre um que funciona nos testes e um que funciona todos os dias por anos.
| Prática | O que fazer | Por que importa |
|---|---|---|
| Confirme primeiro | Responda com o status done assim que o evento for recebido e só depois execute tarefas mais lentas | Mantém a requisição do Gateway curta, mesmo que seus sistemas downstream sejam lentos |
| Enfileire o trabalho | Coloque cada evento recebido em uma fila ou tabela e processe-o separadamente | Lida com as rajadas no início do turno sem perder eventos |
| Valide o AuthToken | Verifique o token em cada requisição antes de confiar nos dados | Impede que outra pessoa envie marcações falsas para sua URL |
| Use HTTPS | Exponha seu webhook somente via HTTPS, com criptografia AES-256 opcional a partir do Gateway | Os dados de presença são dados pessoais e precisam ser protegidos durante a transmissão |
| Torne-o idempotente | Use o OperationID para detectar e ignorar eventos que você já processou | Uma entrega repetida nunca se transforma em um registro de presença duplicado |
| Confie no LogTime para a presença | Registre a presença usando o LogTime, e não o horário em que seu servidor recebeu o evento | Eventos armazenados durante uma interrupção chegam depois, mas mantêm o horário real da marcação |
| Ordene pelo LogTime | Ordene os eventos pelo LogTime antes de calcular as horas | Eventos armazenados podem chegar fora de ordem após uma queda de conexão |
| Registre tudo | Mantenha um registro de cada evento recebido e de cada resposta enviada | Facilita a solução de problemas e as auditorias |
|
Planeje para rajadas, não para médias Uma unidade com 300 funcionários pode receber quase nada na maior parte do dia e, então, 300 eventos em dez minutos na troca de turno. Projete seu receptor para esse pico. Confirmar rapidamente e enfileirar o trabalho é a forma mais simples de lidar com isso. |
Onde o webhook pode ficar
Seu webhook precisa de um endereço HTTPS público que o Gateway consiga acessar. Pode ser um endpoint na sua própria aplicação, uma pequena função em nuvem ou um webhook de entrada em uma ferramenta de automação como n8n ou Make. Seus dispositivos, por si só, não precisam de um IP público. Unidades atrás de firewalls podem se conectar ao Gateway pelo Hybrid Connector, que funciona por meio de uma conexão de saída.
|
Seu sistema decide o que acontece em seguida O Gateway entrega os eventos verificados e aguarda sua confirmação. O que acontece depois, como gravar no seu HRMS, atualizar um painel, enviar um aviso de atraso ou iniciar um fluxo de trabalho, é decidido pelo seu próprio software e pelas suas regras. |
05 · Usando Os Dois Juntos
Onde o Polling Ainda Tem Seu Lugar
Webhooks devem ser o padrão para dados biométricos em tempo real. Mas buscar dados sob demanda ainda tem funções úteis e específicas. As integrações mais sólidas usam webhooks para a entrega em tempo real e buscas pontuais sob demanda para conferência e recuperação.
| Situação | Melhor abordagem | Por quê |
|---|---|---|
| Presença ao vivo, painéis, notificações | Webhooks (Callback API) | Os dados chegam no instante em que a marcação acontece |
| Seu servidor ficou offline por um período | Buscar logs sob demanda | Preencher qualquer lacuna e confirmar que nada foi perdido |
| Conciliação noturna ou semanal | Buscar logs em uma programação | Comparar com o que os webhooks entregaram, como uma rede de segurança |
| Configurando uma nova integração | Buscar logs históricos uma única vez | Importar o histórico existente antes que os webhooks assumam |
| Auditoria de um período específico | Buscar logs desse período | Gerar um registro completo para revisão |
Para essas tarefas, a Cams RESTful API inclui operações para carregar logs dos dispositivos. Usada de forma ocasional e intencional, a busca de logs complementa os webhooks em vez de competir com eles. A diferença está na intenção: você busca quando tem um motivo, em vez de perguntar a cada minuto por precaução.
Perguntas Frequentes
|
O polling é alguma vez melhor que webhooks para dados biométricos? O polling pode ser mais simples quando seu sistema não consegue expor nenhum endpoint público, ou para importações históricas pontuais. Para dados contínuos de presença e controle de acesso, os webhooks são mais rápidos, mais leves para dispositivos e redes e mais fáceis de escalar entre unidades. |
|
O que acontece com as marcações se meu servidor de webhook estiver fora do ar? Se o seu servidor de webhook estiver fora do ar, os dados de presença serão armazenados na fila da Cams. Assim que o seu servidor voltar a ficar online, os registros em fila serão enviados automaticamente ao seu servidor. A fila é reiniciada automaticamente a cada 3 horas, e você também pode reiniciá-la manualmente a qualquer momento pelo Cams Portal. Isso garante que os registros de presença não sejam perdidos por causa de indisponibilidade temporária do servidor. |
|
Meus dispositivos biométricos precisam de um IP público para os webhooks funcionarem? Não. Sua URL de webhook precisa ser acessível pelo Gateway, mas seus dispositivos não. Unidades sem IP público podem se conectar pelo Hybrid Connector, que usa uma conexão de saída. |
|
Posso receber webhooks no n8n, no Make ou no Zapier? Sim. Qualquer ferramenta que consiga receber um webhook de entrada consegue receber eventos da Callback da Cams. O n8n e o Make também podem devolver diretamente a confirmação done exigida. O Zapier pode precisar de um pequeno relay à sua frente para enviar essa resposta. |
|
Por que LogTime e Time são diferentes no payload? LogTime é o momento em que a pessoa realmente fez a marcação, registrado com o deslocamento do fuso horário do dispositivo. Time é o carimbo de data e hora da própria mensagem, em GMT. Se um dispositivo estava offline, a mensagem pode ser enviada bem depois da marcação. Use sempre o LogTime para a presença. |
Conclusão: Deixe a Campainha Tocar
O polling fazia sentido quando os dispositivos biométricos só podiam ser lidos sob solicitação e ninguém esperava que os dados de presença fossem em tempo real. Hoje, painéis de RH, sistemas de folha de pagamento, ferramentas de automação e assistentes de IA funcionam melhor com os dados no momento em que existem. Perguntar a um dispositivo a mesma coisa milhares de vezes por dia é uma forma lenta e desperdiçadora de chegar lá.
Os webhooks transformam cada marcação verificada em um evento que seus sistemas recebem imediatamente, sem requisições desperdiçadas e sem o controle frágil do que já foi buscado. Reserve a busca de logs sob demanda para o que ela faz de melhor, preencher lacunas e verificar a integridade, e deixe os webhooks transportarem todo o resto.
O Cams Biometrics Gateway é construído em torno da entrega push. Sua Callback API envia cada marcação verificada ao seu webhook em tempo real, a partir de dispositivos de mais de 15 marcas, em um formato JSON único e consistente. Os modos Hybrid Push entregam eventos push mesmo de dispositivos que não conseguem enviar dados por conta própria, e a RESTful API oferece operações sob demanda, como o carregamento de logs para conciliação. Toda a comunicação ocorre via HTTP/HTTPS, com validação de token de autenticação e criptografia AES-256 opcional. Conheça a plataforma em CamsBiometrics.com e leia a documentação completa da Callback API em developer.camsbiometrics.com.