Webhooks et architecture event-driven : connecter ses services open source en temps réel

Dans une infrastructure auto-hébergée composée de multiples briques — CKAN, Gitea, Keycloak, Nextcloud, Superset — chaque service fonctionne souvent en silo. Les utilisateurs naviguent d’un outil à l’autre, les données se désynchronisent, et les actions manuelles se multiplient. L’architecture event-driven, appuyée sur les webhooks et un broker de messages léger, permet de relier ces services entre eux et d’automatiser les flux sans couplage fort.

Le problème : des services isolés

Quand un jeu de données est publié sur CKAN, rien ne prévient Superset de rafraîchir son tableau de bord. Quand un utilisateur est créé dans Keycloak, il n’a pas automatiquement son espace Nextcloud. Quand un commit est poussé sur Gitea, le portail de documentation ne se met pas à jour. Ces intégrations, faites manuellement ou par des scripts cron, sont fragiles et mal traçables.

Les webhooks : le mécanisme de base

La plupart des services open source modernes exposent des webhooks — des appels HTTP POST déclenchés par un événement interne. Gitea envoie un webhook à chaque push, merge request ou création de release. CKAN peut être étendu (via ckanext-webhooks ou un plugin personnalisé) pour notifier à chaque création ou mise à jour de dataset. Keycloak supporte les event listeners qui peuvent émettre des webhooks sur les événements d’authentification ou d’administration.

Le webhook est simple à implémenter : un endpoint HTTP reçoit un payload JSON décrivant l’événement. Mais cette approche point-à-point atteint ses limites quand le nombre de connexions entre services augmente.

Introduire un broker de messages léger

Pour aller au-delà du webhook direct, un broker de messages comme Redis (avec ses Streams ou son Pub/Sub) ou NATS offre un point central de transit des événements. Chaque service publie ses événements sur un topic dédié, et les consommateurs s’abonnent aux topics qui les intéressent. Cette architecture découple les producteurs des consommateurs et facilite l’ajout de nouveaux flux sans modifier les services existants.

Redis est souvent déjà présent dans une stack auto-hébergée (cache pour CKAN, sessions pour Nextcloud). Ses Streams offrent la persistance et le suivi de la consommation. NATS, plus léger encore, excelle pour les architectures à haute fréquence d’événements et supporte nativement le pattern request-reply.

Exemples de flux concrets

Voici quelques scénarios d’intégration réalisables avec cette approche :

CKAN → Superset : à chaque publication d’un nouveau jeu de données, un événement déclenche l’import automatique de la source dans Superset et la création d’un tableau de bord par défaut.
Keycloak → Nextcloud + Gitea : la création d’un compte utilisateur dans Keycloak provoque automatiquement la création de son espace de fichiers Nextcloud et de son compte Gitea, via les API respectives.
Gitea → site statique : un push sur la branche main d’un dépôt de documentation déclenche la régénération du site (Hugo, MkDocs) et son déploiement.
Monitoring → alertes : un événement Prometheus (alerte résolue ou déclenchée) est relayé vers un canal de notification unifié via le broker.

Concevoir un micro-service de routage

Le cœur de l’architecture est un petit service — en Python avec FastAPI ou en Go — qui joue le rôle de routeur d’événements. Il reçoit les webhooks des différents services, normalise les payloads dans un format commun (type d’événement, source, timestamp, données), les publie sur le broker, et expose un tableau de bord simple pour suivre les événements traités. Ce service peut être conteneurisé et ajouté à la stack Docker Compose existante.

Un exemple minimal de structure d’événement normalisé :

{
  "event_type": "dataset.created",
  "source": "ckan",
  "timestamp": "2026-03-23T10:30:00Z",
  "payload": {
    "dataset_id": "population-communes-2025",
    "title": "Population des communes 2025",
    "organization": "open-data-ville"
  }
}

Fiabilité et traçabilité

Contrairement aux scripts cron ou aux appels API synchrones, l’architecture event-driven offre plusieurs avantages pour la fiabilité. Les événements peuvent être persistés dans Redis Streams avec un mécanisme de consumer groups, garantissant qu’un message non traité sera re-délivré. Chaque événement est horodaté et loggé, ce qui facilite le débogage. Les consumers peuvent être redémarrés indépendamment sans perdre d’événements. Et si un service est temporairement indisponible, les messages s’accumulent dans le broker et sont traités dès son retour.

Bonnes pratiques

Pour réussir la mise en place d’une architecture event-driven dans un contexte auto-hébergé, quelques principes sont essentiels. Commencer petit : un ou deux flux critiques avant de généraliser. Valider les payloads entrants avec un schéma JSON pour éviter les erreurs silencieuses. Mettre en place un dead-letter queue pour les événements qui échouent après plusieurs tentatives. Documenter chaque type d’événement dans un registre partagé (un simple fichier YAML dans un dépôt Gitea). Enfin, monitorer le broker lui-même avec Prometheus pour détecter les accumulations de messages non consommés.

Aller plus loin

Pour les infrastructures plus matures, des outils comme Apache Kafka ou Temporal offrent des garanties supplémentaires en termes d’ordering, de replay et d’orchestration de workflows complexes. Mais pour une stack de taille modeste, la combinaison webhooks + Redis Streams + un micro-service de routage couvre la majorité des besoins d’intégration avec un coût opérationnel minimal.