Configurer des Webhooks sans IP statique

Le probleme des architectures traditionnelles

La plupart des systemes de pointage biometrique necessitent un serveur local fonctionnant 24h/24 avec une adresse IP statique. L'appareil se connecte a votre serveur via TCP, et si votre serveur tombe en panne ou si votre adresse IP change, vous perdez des donnees de pointage.

Cette architecture a ete concue au debut des annees 2000, lorsque les serveurs sur site etaient la norme. Mais aujourd'hui, la plupart des equipes executent leurs applications dans le cloud — sur AWS, GCP, Azure ou des plateformes comme Railway et Render.

PunchConnect inverse completement ce modele. Au lieu que votre serveur ecoute les connexions des appareils, PunchConnect agit comme intermediaire. Vos appareils envoient les donnees a PunchConnect, et PunchConnect les transmet a votre application via des webhooks.

Comment fonctionnent les webhooks PunchConnect

Lorsqu'un employe pointe a l'arrivee ou au depart sur un appareil biometrique, l'appareil envoie l'evenement au moteur de protocole de PunchConnect. PunchConnect traite l'evenement, normalise les donnees et envoie immediatement une requete HTTP POST a l'URL de rappel que vous avez configuree.

Votre URL de rappel peut etre n'importe quel endpoint accessible publiquement — une fonction serverless sur Vercel, une route Flask sur Railway, un endpoint Express sur Render, ou meme un webhook Zapier.

PunchConnect inclut des tentatives automatiques avec backoff exponentiel. Si votre serveur est temporairement indisponible, les evenements sont mis en file d'attente et renvoyes pendant 72 heures maximum. Aucune donnee n'est perdue.

Etape 1 : Creer un endpoint webhook

Commencez par creer un endpoint simple sur votre serveur qui accepte les requetes POST. Voici un exemple avec 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 });
});

Etape 2 : Enregistrer le webhook

Utilisez l'API PunchConnect pour enregistrer l'URL de votre webhook pour l'appareil :

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}")

Etape 3 : Tester l'integration

PunchConnect fournit un endpoint de test qui simule un evenement de pointage. Utilisez-le pour verifier que votre webhook fonctionne correctement avant de connecter un appareil reel.

Vous pouvez egalement consulter les journaux de livraison des webhooks dans votre tableau de bord — chaque requete, code de reponse et tentative de renvoi est enregistre pour faciliter le debogage.

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"}'

Considerations de securite

Verifiez toujours les signatures des webhooks. PunchConnect signe chaque payload de webhook avec HMAC-SHA256 en utilisant votre secret webhook. Cela garantit que la requete provient bien de PunchConnect et qu'elle n'a pas ete alteree.

Utilisez HTTPS pour votre URL de rappel. PunchConnect ne livrera pas de webhooks vers des endpoints HTTP non securises en mode production.

Implementez l'idempotence. Dans de rares cas (depassements de delai reseau), PunchConnect peut livrer le meme evenement deux fois. Utilisez le champ event_id pour dedupliquer.

Conclusion

Avec les webhooks PunchConnect, vous n'avez besoin ni d'une IP statique, ni d'un serveur local, ni d'une configuration reseau complexe. Deployez simplement votre application ou vous le souhaitez, exposez un endpoint et recevez des donnees de pointage en temps reel.

L'ensemble de la configuration prend environ 15 minutes — de la creation de votre compte a la reception de votre premier evenement de pointage en direct.