REST API, Webhooks e WebSockets: quando usar cada um

As três setas

Os três mecanismos se diferenciam por uma única variável: quem inicia a comunicação.

• REST API: você inicia. Seu backend pede dados e recebe uma resposta. Pergunta → resposta, e a conexão morre.
• Webhooks: a plataforma inicia. Quando ocorre um evento, seu endpoint recebe um POST com os dados. Você não pergunta: recebes um empurrão.
• WebSockets: você inicia uma vez e o canal fica aberto. Ambas as partes enviam a qualquer momento, sem abrir conexão por mensagem.

Todo o resto — latência, complexidade, escalonamento — é consequência dessa diferença. Agora sim, caso por caso.

REST: para consultar, gerenciar e conciliar

REST é o mecanismo natural para tudo o que não depende de algo acontecer no momento: relatórios de ponto por intervalo de datas, auditoria de acessos, gestão de usuários e credenciais, estado dos terminais. É fácil de depurar (um curl e pronto), tolerante a falhas (você tenta de novo e segue) e não exige nada especial na sua infraestrutura.

Na API Connect, a API REST é também a fonte da verdade: mesmo que você consuma eventos em tempo real, sua conciliação de folha de pagamento e seus relatórios oficiais devem se apoiar nos relatórios REST com paginação — assim você não depende de um mecanismo ao vivo não ter falhado num instante.

Webhooks: para reagir ao que acontece

Quando a lógica do seu SaaS precisa agir no momento — notificar a portaria, marcar o ponto ao vivo, disparar um alerta por acesso fora do horário — consultar em loop é desperdício de chamadas de API e latência desnecessária. O webhook inverte a seta: a plataforma faz POST do evento na URL que você configura.

A API Connect permite configurar a URL do webhook (com token opcional para autenticar a entrega) e envia um POST JSON para cada evento:

// Tu endpoint recibe el evento de la plataforma
app.post('/api-connect/eventos', (req, res) => {
  // Verifica el token de entrega antes de procesar
  if (req.headers.authorization !== `Bearer ${process.env.WEBHOOK_TOKEN}`) {
    return res.sendStatus(403);
  }

  const evento = req.body;
  // Ejemplo de payload de marcación:
  // { "Event Type": "Punch", "Event Description": "Access granted – door opened",
  //   "Serial number": "SN...", "Pin": "1234", "Date": "2026-09-14", "Time": "14:30:25" }

  console.log(evento["Pin"], evento["Date"], evento["Time"]);
  res.sendStatus(200); // responde rápido; procesa después
});

WebSockets: para UI ao vivo, não para o seu backend

O websocket brilha num caso muito específico: interface de usuário que precisa de streaming de alta frequência — um painel de acessos ao vivo que atualiza ao mesmo tempo em 50 telas. O canal persistente evita o custo de abrir conexões por mensagem e permite enviar a todos os assinantes de uma vez.

Mas cuidado com a armadilha clássica: manter uma conexão WebSocket por usuário é uma responsabilidade operacional séria (reconexões, balanceamento, fan-out). Em integrações de hardware, o padrão saudável é: o webhook ou stream chega ao seu backend, e seu backend decide como enviá-lo aos navegadores com seu próprio mecanismo de tempo real (que muitos SaaS já têm).

A tabela de decisão

A arquitetura recomendada em uma frase

Webhook para o urgente, REST para a verdade, e seu próprio tempo real para as telas. Com essa combinação, um acesso concedido às 14:30:25 gera o alerta em segundos (webhook), a folha de pagamento do fim do mês concilia com o relatório oficial (REST) e o painel do supervisor se preenche ao vivo (seu canal de distribuição).

Perguntas frequentes