Configurando Webhooks Sem IP Fixo

O problema com configurações tradicionais

A maioria dos sistemas biométricos de ponto exige um servidor local funcionando 24 horas com um endereço IP fixo. O dispositivo se conecta ao seu servidor via TCP, e se o servidor cair ou o IP mudar, você perde os dados de ponto.

Essa arquitetura foi projetada no início dos anos 2000, quando servidores on-premise eram o padrão. Mas hoje, a maioria das equipes executa suas aplicações na nuvem — na AWS, GCP, Azure ou plataformas como Railway e Render.

O PunchConnect inverte esse modelo completamente. Em vez do seu servidor aguardar conexões dos dispositivos, o PunchConnect atua como intermediário. Seus dispositivos enviam dados para o PunchConnect, e o PunchConnect os encaminha para sua aplicação via webhooks.

Como os webhooks do PunchConnect funcionam

Quando um funcionário registra entrada ou saída em um dispositivo biométrico, o dispositivo envia o evento para o motor de protocolo do PunchConnect. O PunchConnect processa o evento, normaliza os dados e imediatamente envia uma requisição HTTP POST para a URL de callback configurada.

Sua URL de callback pode ser qualquer endpoint acessível publicamente — uma função serverless no Vercel, uma rota Flask no Railway, um endpoint Express no Render ou até mesmo um webhook do Zapier.

O PunchConnect inclui retentativas automáticas com backoff exponencial. Se o seu servidor estiver temporariamente indisponível, os eventos são enfileirados e retentados por até 72 horas. Nenhum dado é perdido.

Passo 1: Crie um endpoint de webhook

Primeiro, crie um endpoint simples no seu servidor que aceite requisições POST. Aqui está um exemplo usando Express.js:

app.post('/api/attendance', (req, res) => {
  const { event, employee_id, timestamp, device_serial } = req.body;

  // Verify the webhook signature
  const signature = req.headers['x-punchconnect-signature'];
  if (!verifySignature(req.body, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process the attendance event
  console.log(`${event}: ${employee_id} at ${timestamp}`);

  // Always respond with 200 to acknowledge receipt
  res.status(200).json({ received: true });
});

Passo 2: Registre o webhook

Use a API do PunchConnect para registrar a URL do seu webhook para o dispositivo:

from punchconnect import PunchConnect

client = PunchConnect(api_key="pc_live_your_api_key")

webhook = client.webhooks.create(
    device_id="dev_abc123",
    url="https://your-app.com/api/attendance",
    events=["punch_in", "punch_out"],
    secret="whsec_your_signing_secret"
)

print(f"Webhook active: {webhook.id}")

Passo 3: Teste a integração

O PunchConnect fornece um endpoint de teste que simula um evento de ponto. Use-o para verificar se o seu webhook está funcionando corretamente antes de conectar um dispositivo real.

Você também pode visualizar os logs de entrega de webhooks no seu painel — cada requisição, código de resposta e tentativa de retentativa é registrada para depuração.

curl -X POST https://api.punchconnect.com/v1/webhooks/test \
  -H "Authorization: Bearer pc_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"webhook_id": "whk_abc123", "event": "punch_in"}'

Considerações de segurança

Sempre verifique as assinaturas dos webhooks. O PunchConnect assina cada payload de webhook usando HMAC-SHA256 com o seu segredo de webhook. Isso garante que a requisição veio genuinamente do PunchConnect e não foi adulterada.

Use HTTPS para sua URL de callback. O PunchConnect não entregará webhooks para endpoints HTTP simples no modo de produção.

Implemente idempotência. Em casos raros (timeouts de rede), o PunchConnect pode entregar o mesmo evento duas vezes. Use o campo event_id para deduplicação.

Conclusão

Com os webhooks do PunchConnect, você não precisa de IP fixo, servidor local ou rede complexa. Basta implantar sua aplicação em qualquer lugar, expor um endpoint e receber dados de ponto em tempo real.

Toda a configuração leva cerca de 15 minutos — desde a criação da sua conta até o recebimento do primeiro evento de ponto ao vivo.