Tutorial

Configurer des Webhooks Biométriques Sans IP Fixe

Vos dispositifs biométriques n'ont pas besoin d'une IP fixe ni d'un serveur local. Apprenez à configurer des webhooks cloud qui envoient les données de présence en temps réel à n'importe quel endpoint — avec du code prêt pour la production en Node.js, Python et cURL.

PunchConnect Team·Mar 27, 2026·9 min read

Introduction

Votre pointeuse biométrique se trouve dans le hall d'accueil. Votre application tourne sur AWS. Le dispositif ne peut pas joindre votre serveur, et votre serveur ne peut pas joindre le dispositif. C'est le problème fondamental que chaque équipe rencontre quand elle essaie d'obtenir des données de présence en temps réel dans son application cloud.

La solution traditionnelle — un serveur local avec une IP fixe qui tourne 24h/24 — a été conçue pour un monde où les applications étaient hébergées sur site. En 2026, votre app tourne sur Vercel, Railway, Render ou un cluster Kubernetes. Vous avez besoin de webhooks, pas de boucles de polling.

Ce guide vous accompagne dans la configuration de webhooks biométriques avec PunchConnect. Du zéro à la réception d'événements de pointage en direct en moins de 15 minutes. Sans IP fixe. Sans VPN. Sans serveur local.

Comment Fonctionnent les Webhooks Biométriques

Un webhook est simplement une requête HTTP POST que PunchConnect envoie à votre serveur chaque fois qu'un événement se produit — un employé pointe, une nouvelle empreinte est enregistrée, ou un dispositif se déconnecte. Vous donnez une URL à PunchConnect, et il vous pousse les événements en temps réel.

La différence clé avec les installations traditionnelles : votre serveur ne fait pas de polling. Il ne se connecte pas au dispositif. Il écoute simplement les requêtes HTTP entrantes comme n'importe quel endpoint web classique.

Voici ce qui se passe étape par étape :

1. L'employé pointe sur le dispositif biométrique (empreinte, visage, badge)
2. Le dispositif pousse l'événement vers le moteur protocolaire de PunchConnect (sortant depuis le dispositif — pas besoin d'IP fixe)
3. PunchConnect normalise les données brutes en un payload JSON propre
4. Le webhook se déclenche — PunchConnect envoie un HTTP POST à votre URL de callback enregistrée
5. Votre app traite l'événement (mise à jour base de données, déclenchement workflow, envoi notification)

Si votre endpoint retourne une erreur 5xx ou expire, PunchConnect retente automatiquement avec backoff exponentiel pendant 72 heures. Aucune donnée de pointage n'est perdue.

Étape 1 : Créer Votre Endpoint Webhook

Votre endpoint webhook est simplement une route HTTP normale qui accepte les requêtes POST :

Node.js (Express) :

Python (Flask) :

```python
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook/attendance', methods=['POST'])
def handle_punch():
data = request.json
employee_id = data['employee_id']
timestamp = data['timestamp']
punch_type = data['punch_type']

print(f"Pointage reçu : Employé {employee_id} à {timestamp}")

# Votre logique : sauvegarder en BDD, notifier le manager, mettre à jour le SIRH...

return jsonify({"received": True}), 200

if __name__ == '__main__':
app.run(port=3000)
```

Déployez ceci sur n'importe quelle plateforme cloud — OVH, Scaleway, Railway, Render, AWS Lambda, un VPS. Cette URL devient votre callback.

javascript

const express = require('express');
const app = express();
app.use(express.json());

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

  console.log(`Pointage reçu : Employé ${employee_id} à ${timestamp}`);

  // Votre logique : sauvegarder en BDD, notifier le manager, mettre à jour le SIRH...

  res.status(200).json({ received: true });
});

app.listen(3000, () => console.log('Webhook listener sur le port 3000'));

Étape 2 : Enregistrer Votre Webhook avec PunchConnect

Utilisez l'API PunchConnect pour indiquer au système où envoyer les événements :

Le champ secret est essentiel — PunchConnect l'utilise pour signer chaque payload webhook afin que vous puissiez vérifier l'authenticité.

bash

curl -X POST https://api.punchconnect.com/v1/webhooks \
  -H "Authorization: Bearer VOTRE_CLE_API" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://votre-app.railway.app/webhook/attendance",
    "events": ["attendance.punch"],
    "secret": "votre-secret-webhook"
  }'

Étape 3 : Configurer Votre Dispositif

Ajoutez votre dispositif biométrique à PunchConnect via le tableau de bord. Le dispositif se connecte en sortant vers le cloud PunchConnect — pas de redirection de port, pas d'IP fixe, pas de VPN.

La configuration prend environ 5 minutes par dispositif dans le tableau de bord :

1. Ajouter le dispositif (numéro de série + modèle)
2. Pointer l'adresse serveur du dispositif vers l'endpoint PunchConnect
3. Le dispositif se connecte automatiquement et commence à pousser les données
4. PunchConnect transfère les événements à votre webhook enregistré

Étape 4 : Vérifier les Signatures Webhook

Ne faites jamais confiance à un webhook entrant aveuglément. PunchConnect signe chaque payload avec HMAC-SHA256 en utilisant votre secret webhook. Vérifiez toujours avant de traiter.

Ceci est particulièrement important pour la conformité RGPD — vous devez garantir l'intégrité et l'authenticité des données biométriques traitées. Avec PunchConnect, chaque événement est signé et traçable, ce qui facilite la documentation exigée par la CNIL.

javascript

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  return crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}

Étape 5 : Gérer les Retries et l'Idempotence

PunchConnect retente les livraisons échouées avec backoff exponentiel : 1 min → 5 min → 15 min → 1 heure → 4 heures, pendant 72 heures maximum.

Implémentez toujours l'idempotence avec le champ `event_id` :

javascript

const processedEvents = new Set(); // Utilisez Redis ou une BDD en production

app.post('/webhook/attendance', (req, res) => {
  const { event_id } = req.body;
  if (processedEvents.has(event_id)) {
    return res.status(200).json({ received: true, duplicate: true });
  }
  processedEvents.add(event_id);
  // Traiter l'événement...
  res.status(200).json({ received: true });
});

Checklist de Production

Avant de passer en production :

- ✅ Endpoint HTTPS — PunchConnect ne livre pas vers du HTTP en production
- ✅ Vérification de signature — validez chaque requête avec HMAC-SHA256
- ✅ Idempotence — gérez les doublons avec event_id
- ✅ Réponse 200 en moins de 10 secondes — retournez vite, traitez en async si besoin
- ✅ Journalisation — enregistrez chaque webhook pour le débogage
- ✅ Conformité RGPD — documentez le traitement des données biométriques (obligation CNIL)

Guides Connexes

- Présence Biométrique Sans IP Fixe — pourquoi les IP fixes sont la mauvaise approche
- Intégration Webhook ZKTeco — configuration spécifique pour les terminaux ZKTeco
- API REST Dispositif Biométrique — référence API complète avec exemples de code
- Sécuriser les Données Biométriques en Transit — chiffrement, signatures et conformité

Questions Fréquentes

Ai-je besoin d'une IP fixe pour recevoir des webhooks ?

Non. C'est justement le principe. Votre endpoint webhook a juste besoin d'une URL publique — n'importe quelle plateforme cloud (OVH, Scaleway, AWS, Railway) en fournit une automatiquement. Le dispositif se connecte en sortant vers PunchConnect, et PunchConnect se connecte en sortant vers votre URL.

Que se passe-t-il si mon serveur est hors service quand un pointage a lieu ?

PunchConnect met l'événement en file d'attente et retente avec backoff exponentiel pendant 72 heures. Quand votre serveur revient en ligne, tous les événements en attente sont livrés dans l'ordre. Zéro perte de données.

Puis-je recevoir des webhooks sur une fonction serverless ?

Oui. Les webhooks PunchConnect fonctionnent avec AWS Lambda, Vercel Functions, Cloudflare Workers, Google Cloud Functions — toute plateforme pouvant recevoir des requêtes HTTP POST.

Comment déboguer les livraisons webhook échouées ?

Le tableau de bord PunchConnect affiche un journal complet pour chaque webhook : corps de la requête, code de réponse, temps de réponse et historique des retries. Vous pouvez aussi rejouer n'importe quelle livraison échouée en un clic.

Est-ce conforme au RGPD ?

PunchConnect est conçu pour la conformité RGPD. Les données biométriques sont chiffrées en transit (TLS 1.3), chaque webhook est signé pour garantir l'intégrité, et vous gardez le contrôle total de vos données — hébergées en Europe sur demande.

---

*Prêt à recevoir des données de présence en temps réel dans votre app cloud ? Commencez votre essai gratuit — premier dispositif offert, configuration en moins de 15 minutes.*

Configurer des Webhooks Biométriques Sans IP Fixe

Introduction

Comment Fonctionnent les Webhooks Biométriques

Étape 1 : Créer Votre Endpoint Webhook

Étape 2 : Enregistrer Votre Webhook avec PunchConnect

Étape 3 : Configurer Votre Dispositif

Étape 4 : Vérifier les Signatures Webhook

Étape 5 : Gérer les Retries et l'Idempotence

Checklist de Production

Guides Connexes

Questions Fréquentes

Ai-je besoin d'une IP fixe pour recevoir des webhooks ?

Que se passe-t-il si mon serveur est hors service quand un pointage a lieu ?

Puis-je recevoir des webhooks sur une fonction serverless ?

Comment déboguer les livraisons webhook échouées ?

Est-ce conforme au RGPD ?

Articles connexes

Connecter ZKTeco à Odoo : L'Approche API Cloud (Sans VPN, Sans Logiciel Local)

Intégration Webhook ZKTeco : Pipelines de Présence en Temps Réel via API REST

Intégration API de Lecteur d'Empreintes : Guide Développeur pour la Biométrie Cloud