Webhooks : notifications en temps réel pour les changements d'architecture

La semaine dernière, une équipe m'a raconté qu'ils avaient renommé un système central dans Archyl — changé "UserService" en "AccountService" dans tout le modèle C4, mis à jour les relations, réécrit l'ADR. Un travail propre et rigoureux. Le problème ? L'équipe plateforme qui dépendait de ce système l'a découvert quatre jours plus tard, quand leur pipeline de déploiement référençait un nom qui n'existait plus.

Personne ne les avait prévenus. Pas par négligence — il n'y avait tout simplement pas de mécanisme pour ça. La documentation d'architecture fonctionne typiquement en mode pull. On va regarder le diagramme. On va lire l'ADR. Si on ne va pas regarder, on ne sait pas.

C'est exactement le même schéma qui a pénalisé le développement logiciel avant que les notifications CI/CD ne deviennent la norme. Les changements de code étaient quelque chose qu'on découvrait quand on faisait un pull de main. Aujourd'hui, chaque merge, chaque build échoué, chaque déploiement déclenche une notification quelque part. Les changements d'architecture méritent le même traitement.

Des notifications push pour votre architecture

Archyl supporte désormais les webhooks. Quand quelque chose change dans votre modèle C4 — un système est créé, un conteneur est supprimé, une relation est mise à jour, une release est livrée — Archyl envoie un HTTP POST vers n'importe quel endpoint que vous configurez, avec un payload JSON décrivant exactement ce qui s'est passé.

L'idée est simple : votre architecture est un système vivant. Les personnes et les outils devraient pouvoir s'abonner à ses changements de la même façon qu'ils s'abonnent aux événements de déploiement ou aux notifications de pull request. Au lieu de demander "est-ce que quelque chose a changé ?", la réponse vient à vous.

44 types d'événements

On ne voulait pas livrer un système de notifications qui ne couvrait que la moitié du modèle. Les webhooks se déclenchent sur tout ce qu'Archyl suit :

Éléments C4 — Création, mise à jour et suppression de systèmes, conteneurs, composants et éléments de code. Le cœur de votre modèle d'architecture.

Relations — Quand des connexions entre éléments sont créées, modifiées ou supprimées. C'est souvent le signal le plus important — une nouvelle dépendance entre deux systèmes est le type de changement que plusieurs équipes doivent connaître.

ADRs & Documentation — Création, mise à jour ou suppression d'Architecture Decision Records et de documents projet. Quand quelqu'un rédige un nouvel ADR expliquant pourquoi l'équipe migre de REST vers gRPC, les personnes concernées devraient en être informées immédiatement, pas trois sprints plus tard.

Flows — Changements de flux utilisateur et système. Nouveaux flux, étapes mises à jour, flux supprimés.

Overlays — Changements de regroupements visuels sur vos diagrammes.

Releases — Événements de déploiement à travers les environnements. Combiné avec la gestion des releases, ça vous donne un pipeline complet de notifications de déploiement en mode push.

Requests — Demandes de changement d'architecture ouvertes, revues ou fusionnées.

Contrats API & Event Channels — Changements de spécifications et mises à jour de messaging asynchrone liés à votre architecture.

Discovery & Insights — Complétions de discovery IA et nouveaux insights d'architecture.

Quarante-quatre types d'événements au total. Vous choisissez ceux qui vous intéressent — abonnez-vous à tout, ou juste aux cinq événements qui comptent pour votre workflow.

Comment ça marche

Configurer un webhook prend environ trente secondes.

Vous lui donnez un nom (quelque chose de descriptif — "Notifications Slack", "Sync audit log", "Déclencheur CI"). Vous fournissez une URL — n'importe quel endpoint HTTP capable de recevoir un POST. Vous définissez optionnellement un secret pour la vérification de signature. Puis vous choisissez quels événements doivent le déclencher.

Vous pouvez aussi limiter un webhook à des projets spécifiques. Un webhook à l'échelle de l'organisation qui se déclenche sur chaque changement de chaque projet est utile pour l'audit logging. Un webhook limité à un projet qui ne se déclenche que sur les événements de release de votre système de paiement est utile pour l'équipe qui en est responsable.

Quand un événement correspondant survient, Archyl envoie un HTTP POST à votre URL avec un payload JSON contenant :

• Type d'événement — Lequel des 44 événements a déclenché cette livraison
• Entité — Les détails complets de l'élément qui a changé
• Acteur — Qui a fait le changement (ID utilisateur, nom, email)
• Projet — Dans quel projet c'est arrivé
• Timestamp — Quand le changement a eu lieu
• Organisation — À quelle organisation ça appartient

Le payload vous donne tout ce dont vous avez besoin pour réagir au changement — l'afficher, le logger, déclencher un pipeline ou le synchroniser vers un autre système.

Sécurité : signatures HMAC-SHA256

Chaque requête webhook inclut un header X-Archyl-Signature au format sha256=<hex digest> — un hash HMAC-SHA256 du corps brut de la requête, calculé à partir de votre secret. Vous recevez aussi X-Archyl-Event (le type d'événement) et User-Agent: Archyl-Webhook/1.0 pour identifier la source.

Côté réception, vous supprimez le préfixe sha256=, recalculez le hash HMAC-SHA256 avec votre copie du secret sur les octets bruts du corps, et comparez en utilisant une comparaison en temps constant. S'ils correspondent, la requête est authentique. S'ils ne correspondent pas, quelqu'un vous envoie des événements falsifiés.

C'est le même schéma de signature utilisé par GitHub, Stripe et la plupart des fournisseurs de webhooks. C'est simple, bien compris et facile à implémenter dans n'importe quel langage. Pas de flow OAuth, pas de rotation de tokens, pas de gestion de certificats. Juste un secret partagé et un hash. Consultez la webhook docs pour des exemples complets de vérification en Go, Node.js et Python.

Si vous ne définissez pas de secret, le header de signature est omis. Acceptable pour des endpoints internes derrière un VPN. Déconseillé pour tout ce qui est exposé à Internet.

Ce que vous pouvez construire avec ça

Le cas d'usage le plus évident, c'est les notifications dans un chat. Slack, Microsoft Teams et Discord supportent tous les webhooks entrants — collez leur URL dans Archyl, sélectionnez les événements qui vous intéressent, et les changements d'architecture commencent à apparaître dans votre channel. Un nouveau système a été ajouté. Un ADR a été approuvé. Une release a été livrée en production. Votre équipe le voit sans ouvrir Archyl.

Mais les notifications ne sont que le début.

Synchronisation vers des systèmes externes — Poussez les changements d'architecture vers un CMDB, un wiki interne ou un catalogue de services. Quand un conteneur est renommé dans Archyl, votre catalogue de services se met à jour automatiquement.

Déclenchement de pipelines CI/CD — Quand une demande de changement d'architecture est fusionnée, lancez un pipeline qui régénère la config d'infrastructure, met à jour les modules Terraform, ou valide que le déploiement réel correspond à l'architecture documentée.

Piste d'audit — Transférez chaque événement vers un système de logging externe — Elasticsearch, Splunk, une simple base de données en append-only. Sept jours d'historique de livraison dans Archyl, c'est utile pour le débogage ; un log externe permanent, c'est utile pour la conformité.

Dashboards personnalisés — Construisez un dashboard interne qui réagit aux événements d'architecture en temps réel. Suivez la fréquence des changements d'architecture, quelles équipes sont les plus actives, quels systèmes sont les plus volatils.

L'idée, c'est que les webhooks transforment Archyl en source d'événements. Votre modèle d'architecture devient quelque chose auquel d'autres systèmes peuvent s'abonner, réagir et s'appuyer.

Suivi des livraisons

Chaque livraison de webhook est loggée. Vous pouvez voir l'historique complet de n'importe quel webhook : quel événement l'a déclenché, le payload de la requête envoyée, le code de statut de la réponse, le corps de la réponse, et les timestamps d'envoi et de réception.

Les livraisons sont conservées pendant sept jours. Assez long pour déboguer des problèmes d'intégration, assez court pour qu'on ne stocke pas les corps de réponse de votre endpoint indéfiniment.

Quand une livraison échoue — un 500 de votre serveur, un timeout, une erreur de résolution DNS — elle apparaît avec un statut rouge. Vous pouvez inspecter l'erreur, corriger votre endpoint, et relancer en un clic. Le retry envoie exactement le même payload, pour que votre endpoint traite l'événement original comme s'il avait réussi la première fois.

Pas de retries automatiques. On a envisagé le backoff exponentiel, mais en pratique, la plupart des échecs de webhook sont soit transitoires (votre serveur redémarrait) soit structurels (l'URL est fausse). Pour les échecs transitoires, le bouton de retry manuel est plus rapide que d'attendre le backoff. Pour les échecs structurels, les retries automatiques ne font que générer du bruit.

Pour démarrer

1. Allez dans Paramètres de l'organisation > Webhooks
2. Cliquez sur Créer un Webhook
3. Entrez un nom, collez l'URL de votre endpoint, définissez un secret
4. Sélectionnez les événements auxquels vous voulez vous abonner
5. Filtrez optionnellement sur des projets spécifiques
6. Cliquez sur Envoyer un test pour vérifier que votre endpoint reçoit bien le payload
7. Sauvegardez, et c'est en ligne

La livraison de test envoie un événement ping avec un payload d'exemple pour que vous puissiez confirmer que votre endpoint est joignable, que votre secret est correctement configuré, et que votre handler traite le JSON comme attendu. Faites-le avant de vous abonner aux vrais événements.

L'architecture comme flux d'événements

On construit depuis le début une vision de la documentation d'architecture qui n'est pas un artefact statique — c'est une partie vivante et connectée de votre workflow de développement. Les Intégrations Marketplace apportent des données externes dans votre architecture. Les webhooks poussent les données d'architecture vers vos outils.

La combinaison est puissante. Votre espace d'architecture n'est pas juste un endroit où aller regarder des diagrammes. C'est un hub qui reçoit des données opérationnelles de vos outils de monitoring et émet des événements de changement vers vos outils de communication et d'automatisation. Les données circulent dans les deux sens.

De la documentation d'architecture que personne ne regarde, c'est inutile. De la documentation d'architecture qui vous notifie quand c'est important — ça, c'est de l'infrastructure.

Envie de voir comment d'autres fonctionnalités connectent votre architecture à votre workflow ? Découvrez les Intégrations Marketplace pour afficher des données temps réel sur vos diagrammes, ou la Gestion des Releases pour le suivi des déploiements à travers votre modèle C4.