Perguntas Frequentes Sobre Integração de Ocupação via Webhook

A maioria dos problemas com webhooks de ocupação não vem do sensor. Vem do que acontece depois que o evento sai do dispositivo: um endpoint que retorna 500 durante um deploy, uma fila que engole eventos silenciosamente, ou um payload que muda de formato sem aviso e quebra o parser do sistema de HVAC. Se você já integrou contagem de pessoas em BMS, dashboards ou lógica de climatização, sabe que o desafio real é operacional, não conceitual.

Este FAQ responde às perguntas que equipes de smart building, integradores e desenvolvedores realmente fazem antes de colocar uma integração de ocupação via webhook em produção.

Qual a diferença entre webhook e polling de API para dados de ocupação?

Com polling, seu sistema pergunta ao servidor "quantas pessoas há agora?" a cada X segundos. Isso gera chamadas desperdiçadas quando nada muda e latência quando algo muda logo após a última consulta. Um webhook inverte a relação: o servidor da Vemco envia um POST HTTP para o seu endpoint no momento em que o evento ocorre. Para lógica de ocupação em tempo real — acender luzes de uma zona, ajustar ventilação, liberar uma sala de reunião — o webhook reduz a latência e o volume de requisições. Para relatórios históricos ou reconciliação diária, o polling ou uma exportação em lote ainda faz mais sentido.

O que vem dentro do payload?

Um payload típico de ocupação carrega contagens agregadas — entradas, saídas, ocupação atual — associadas a um identificador de zona ou sensor e um timestamp. Não há imagens, não há identidade de pessoas, não há dados que permitam rastrear um indivíduo. A Vemco trabalha com contagem em conformidade com o GDPR: sem identificação pessoal, com exclusão de funcionários e apenas números agregados. Isso importa na hora de integrar, porque significa que o payload não precisa passar por camadas extras de anonimização do seu lado — ele já chega sem PII.

Vale confirmar com a equipe da Vemco o esquema exato de campos e a versão do payload antes de escrever seu parser, porque tratar o campo de zona como string em vez de inteiro evita retrabalho quando você adiciona novos sensores.

Como garanto que meu endpoint aguenta o volume?

Duas regras que evitam a maioria dos incidentes:

• Responda rápido, processe depois. Seu endpoint deve retornar 200 em milissegundos e enfileirar o evento para processamento assíncrono. Se você tentar rodar toda a lógica de negócio antes de responder, um pico de eventos em horário de pico vai estourar timeouts.
• Seja idempotente. Webhooks podem ser reenviados após falha. Use o ID do evento para descartar duplicatas, ou você vai contar a mesma entrada duas vezes e a ocupação vai divergir da realidade.

O que acontece se meu servidor cair?

Essa é a pergunta que separa uma integração amadora de uma pronta para produção. Confirme a política de retentativa: quantas tentativas, com que intervalo, e se há backoff exponencial. Um erro comum é depender só do webhook como fonte de verdade. Mantenha um endpoint de consulta para reconciliar o estado após uma indisponibilidade — assim, quando seu serviço voltar, você busca a ocupação atual em vez de tentar reconstruir a partir de eventos possivelmente perdidos.

Como valido que o evento veio mesmo da Vemco?

Um endpoint público que aceita qualquer POST é um convite a problemas. Exija HTTPS, valide a assinatura ou o token compartilhado enviado no cabeçalho e, quando possível, restrinja por IP de origem. A Vemco oferece hospedagem em nuvem pública ou privada e integra com sistemas de TI existentes, então alinhe o modelo de autenticação com o que sua equipe de segurança já usa — não crie um esquema paralelo só para o webhook. Sobre SSO/SAML, residência de dados e certificações específicas, confirme diretamente com a Vemco os detalhes aplicáveis ao seu contrato.

A contagem que chega no webhook é confiável para automação?

Sim, dentro de limites que você precisa entender. O mínimo contratual de acurácia é de 96%, e na prática fica entre 98% e 99% quando as condições permitem — iluminação adequada, layout da loja e comportamento previsível dos visitantes. Nenhum fornecedor sério promete um número fixo garantido, porque um sensor mal posicionado numa entrada com luz solar direta vai render menos que o mesmo sensor num corredor interno estável. Para automação crítica, projete tolerância: uma zona configurada como "vazia" só depois de alguns minutos sem eventos evita desligar a ventilação por causa de um ruído de contagem momentâneo.

Consigo mapear várias zonas para sistemas diferentes?

Consegue, e é aqui que a arquitetura se paga. Em vez de apontar cada sensor diretamente para cada sistema consumidor, coloque uma camada de roteamento entre o webhook e seus destinos. Um evento de ocupação da mesma zona pode alimentar simultaneamente o BMS para climatização, um painel de sinalização digital e o banco de dados de analytics — cada um com sua própria transformação. Isso evita que uma mudança no dashboard exija reconfigurar o sensor.

Quanto tempo leva uma integração dessas?

A parte de código é curta: receber um POST, validar, enfileirar. O que consome tempo é o mapeamento de zonas para a lógica física do prédio, os testes com dados reais e o alinhamento com a equipe de segurança. Empresas que já operam há anos com esse tipo de dado — a Vemco atua desde 2005, com mais de 2000 clientes em mais de 95 países — normalmente têm documentação e ambientes de teste que encurtam essa fase. Peça acesso a um ambiente de sandbox antes de tocar em produção.

Vamos configurar sua integração

Se você está definindo esquema de payload, política de retentativa ou modelo de autenticação para sua integração de ocupação via webhook, a equipe da Vemco pode revisar seu caso concreto e confirmar os detalhes técnicos e de conformidade que se aplicam ao seu projeto. Fale com a Vemco para começar com um ambiente de teste e a documentação do endpoint.