REST API, Webhooks et WebSockets : quand utiliser chacun

Les trois flèches

Les trois mécanismes se distinguent par une seule variable : qui initie la communication.

• REST API : c'est vous qui initiez. Votre backend demande des données et reçoit une réponse. Question → réponse, et la connexion meurt.
• Webhooks : c'est la plateforme qui initie. Quand un événement survient, votre endpoint reçoit un POST avec les données. Vous ne demandez pas : on vous pousse.
• WebSockets : vous initiez une fois et le canal reste ouvert. Les deux parties envoient à tout moment, sans ouvrir de connexion par message.

Tout le reste — latence, complexité, montée en charge — découle de cette différence. Passons aux cas, un par un.

REST : pour consulter, gérer et réconcilier

REST est le mécanisme naturel pour tout ce qui ne dépend pas d'un événement en cours : rapports de pointage par plage de dates, audit des accès, gestion des utilisateurs et des identifiants, état des terminaux. Facile à déboguer (un curl et c'est réglé), tolérant aux pannes (on réessaie et on avance), et il n'exige rien de spécial dans votre infrastructure.

Dans API Connect, l'API REST est aussi la source de vérité : même si vous consommez les événements en temps réel, votre réconciliation de paie et vos rapports officiels doivent s'appuyer sur les rapports REST paginés — ainsi vous ne dépendez pas d'un mécanisme en direct qui aurait raté un instant.

Webhooks : pour réagir à ce qui se passe

Quand la logique de votre SaaS doit agir dans l'instant — notifier la réception, marquer le pointage en direct, déclencher une alerte pour un accès hors horaire — interroger en boucle gaspille des appels API et ajoute de la latence inutile. Le webhook inverse la flèche : la plateforme POSTe l'événement vers l'URL que vous configurez.

API Connect permet de configurer l'URL de webhook (avec un token optionnel pour authentifier la livraison) et envoie un POST JSON pour chaque événement :

// 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 : pour l'UI en direct, pas pour votre backend

Le websocket brille dans un cas très précis : une interface qui a besoin d'un streaming à haute fréquence — un tableau de bord d'accès en direct qui se met à jour simultanément sur 50 écrans. Le canal persistant évite le coût d'ouvrir une connexion par message et permet de pousser vers tous les abonnés d'un coup.

Mais attention au piège classique : maintenir une connexion WebSocket par utilisateur est une lourde responsabilité opérationnelle (reconnexions, répartition de charge, fan-out). Dans les intégrations matérielles, le schéma sain est : le webhook ou le stream arrive dans votre backend, et votre backend décide comment le pousser vers les navigateurs avec son propre mécanisme temps réel (que beaucoup de SaaS ont déjà).

La table de décision

L'architecture recommandée en une phrase

Le webhook pour l'urgent, REST pour la vérité, et votre propre temps réel pour les écrans. Avec cette combinaison, un accès accordé à 14:30:25 génère l'alerte en quelques secondes (webhook), la paie de fin de mois se réconcilie avec le rapport officiel (REST) et le tableau de bord du superviseur se remplit en direct (votre canal de distribution).

Questions fréquentes