Webhooks: Echtzeit-Benachrichtigungen bei Architektur-Änderungen

Letzte Woche erzählte mir ein Team, dass sie ein zentrales System in Archyl umbenannt hatten — von "UserService" zu "AccountService" quer durch das gesamte C4-Modell, inklusive aktualisierter Beziehungen und einem neu geschriebenen ADR. Saubere, gründliche Arbeit. Das Problem? Das Plattform-Team, das von diesem System abhing, erfuhr erst vier Tage später davon, als ihre Deployment-Pipeline einen Namen referenzierte, der nicht mehr existierte.

Niemand hatte sie informiert. Nicht aus Nachlässigkeit — es gab einfach keinen Mechanismus dafür. Architekturdokumentation funktioniert typischerweise nach dem Pull-Prinzip. Man schaut sich das Diagramm an. Man liest den ADR. Wer nicht nachschaut, weiß von nichts.

Das ist dasselbe Muster, das die Softwareentwicklung geplagt hat, bevor CI/CD-Benachrichtigungen zum Standard wurden. Codeänderungen waren früher etwas, das man entdeckte, wenn man den main-Branch pullte. Heute löst jeder Merge, jeder fehlgeschlagene Build, jedes Deployment irgendwo eine Benachrichtigung aus. Architektur-Änderungen verdienen die gleiche Behandlung.

Push-Benachrichtigungen für eure Architektur

Archyl unterstützt jetzt Webhooks. Wenn sich etwas in eurem C4-Modell ändert — ein System wird erstellt, ein Container gelöscht, eine Beziehung aktualisiert, ein Release veröffentlicht — sendet Archyl einen HTTP POST an jeden von euch konfigurierten Endpunkt, mit einem JSON-Payload, der genau beschreibt, was passiert ist.

Die Idee ist einfach: Eure Architektur ist ein lebendiges System. Menschen und Tools sollten dessen Änderungen genauso abonnieren können wie Deploy-Events oder Pull-Request-Benachrichtigungen. Statt zu fragen "Hat sich etwas geändert?", kommt die Antwort zu euch.

44 Event-Typen

Wir wollten kein Benachrichtigungssystem ausliefern, das nur die Hälfte des Modells abdeckt. Webhooks feuern für alles, was Archyl erfasst:

C4-Elemente — Erstellung, Aktualisierung und Löschung von Systemen, Containern, Komponenten und Code-Elementen. Der Kern eures Architekturmodells.

Beziehungen — Wenn Verbindungen zwischen Elementen erstellt, geändert oder entfernt werden. Das ist oft das wichtigste Signal — eine neue Abhängigkeit zwischen zwei Systemen ist genau die Art von Änderung, über die mehrere Teams Bescheid wissen müssen.

ADRs & Dokumentation — Architecture Decision Records und Projektdokumentationen, die erstellt, aktualisiert oder gelöscht werden. Wenn jemand einen neuen ADR schreibt, der erklärt, warum das Team von REST auf gRPC migriert, sollten die betroffenen Personen sofort davon erfahren — nicht erst drei Sprints später.

Flows — Änderungen an User- und System-Flows. Neue Flows, aktualisierte Schritte, gelöschte Flows.

Overlays — Änderungen an visuellen Gruppierungen in euren Diagrammen.

Releases — Deployment-Events über verschiedene Umgebungen hinweg. In Kombination mit dem Release-Management ergibt sich eine vollständige Push-basierte Deployment-Benachrichtigungspipeline.

Requests — Architektur-Änderungsanträge, die geöffnet, überprüft oder gemergt werden.

API Contracts & Event Channels — Änderungen an Spezifikationen und asynchronen Messaging-Updates, die mit eurer Architektur verknüpft sind.

Discovery & Insights — Abgeschlossene KI-gestützte Discoveries und neue Architektur-Insights.

Vierundvierzig Event-Typen insgesamt. Ihr wählt die aus, die euch interessieren — abonniert alles oder nur die fünf Events, die für euren Workflow relevant sind.

So funktioniert es

Das Einrichten eines Webhooks dauert ungefähr dreißig Sekunden.

Ihr gebt ihm einen Namen (etwas Beschreibendes — "Slack-Benachrichtigungen", "Audit-Log-Sync", "CI-Trigger"). Ihr gebt eine URL an — einen beliebigen HTTP-Endpunkt, der POST-Requests empfangen kann. Optional setzt ihr ein Secret zur Signaturverifizierung. Dann wählt ihr aus, welche Events den Webhook auslösen sollen.

Ihr könnt einen Webhook auch auf bestimmte Projekte einschränken. Ein organisationsweiter Webhook, der bei jeder Änderung in jedem Projekt feuert, ist nützlich für Audit-Logging. Ein projektbezogener Webhook, der nur bei Release-Events für euer Payment-System feuert, ist nützlich für das Team, das es betreut.

Wenn ein passendes Event eintritt, sendet Archyl einen HTTP POST an eure URL mit einem JSON-Payload, der Folgendes enthält:

Event-Typ — Welches der 44 Events diese Auslieferung ausgelöst hat
Entity — Die vollständigen Details des geänderten Elements
Akteur — Wer die Änderung vorgenommen hat (User-ID, Name, E-Mail)
Projekt — In welchem Projekt es passiert ist
Zeitstempel — Wann die Änderung stattfand
Organisation — Zu welcher Organisation es gehört

Der Payload liefert euch alles, was ihr braucht, um auf die Änderung zu reagieren — anzeigen, loggen, eine Pipeline triggern oder in ein anderes System synchronisieren.

Sicherheit: HMAC-SHA256-Signaturen

Jeder Webhook-Request enthält einen X-Archyl-Signature-Header im Format sha256=<hex digest> — einen HMAC-SHA256-Hash des rohen Request-Body, berechnet mit eurem Secret. Zusätzlich erhaltet ihr X-Archyl-Event (den Event-Typ) und User-Agent: Archyl-Webhook/1.0, damit ihr die Quelle identifizieren könnt.

Auf der Empfängerseite entfernt ihr das Präfix sha256=, berechnet den HMAC-SHA256-Hash mit eurer Kopie des Secrets gegen die rohen Body-Bytes neu und vergleicht mittels Constant-Time-Vergleich. Stimmen sie überein, ist der Request authentisch. Stimmen sie nicht überein, schickt euch jemand gefälschte Events.

Das ist dasselbe Signaturverfahren, das GitHub, Stripe und die meisten Webhook-Anbieter verwenden. Es ist einfach, gut verstanden und in jeder Programmiersprache leicht zu implementieren. Keine OAuth-Flows, keine Token-Rotation, kein Zertifikatsmanagement. Nur ein gemeinsames Secret und ein Hash. Vollständige Verifizierungsbeispiele in Go, Node.js und Python findet ihr in der Webhook-Dokumentation.

Wenn ihr kein Secret setzt, wird der Signatur-Header weggelassen. In Ordnung für interne Endpunkte hinter einem VPN. Nicht empfohlen für alles, was dem Internet ausgesetzt ist.

Was ihr damit bauen könnt

Der naheliegendste Anwendungsfall sind Chat-Benachrichtigungen. Slack, Microsoft Teams und Discord unterstützen alle eingehende Webhooks — fügt deren URL in Archyl ein, wählt die Events aus, die euch interessieren, und Architektur-Änderungen erscheinen in eurem Channel. Ein neues System wurde hinzugefügt. Ein ADR wurde genehmigt. Ein Release ging in Produktion. Euer Team sieht es, ohne Archyl zu öffnen.

Aber Benachrichtigungen sind nur der Anfang.

Synchronisation mit externen Systemen — Pusht Architektur-Änderungen an eine CMDB, ein internes Wiki oder einen Service-Katalog. Wenn ein Container in Archyl umbenannt wird, aktualisiert sich euer Service-Katalog automatisch.

CI/CD-Pipelines triggern — Wenn ein Architektur-Änderungsantrag gemergt wird, startet eine Pipeline, die Infrastruktur-Konfiguration neu generiert, Terraform-Module aktualisiert oder überprüft, ob das tatsächliche Deployment mit der dokumentierten Architektur übereinstimmt.

Audit-Trail — Leitet jedes Event an ein externes Logging-System weiter — Elasticsearch, Splunk, eine einfache Append-Only-Datenbank. Sieben Tage Auslieferungshistorie in Archyl sind nützlich zum Debuggen; ein permanentes externes Log ist nützlich für Compliance.

Individuelle Dashboards — Baut ein internes Dashboard, das in Echtzeit auf Architektur-Events reagiert. Verfolgt, wie oft sich die Architektur ändert, welche Teams am aktivsten sind, welche Systeme am volatilsten sind.

Der Punkt ist: Webhooks machen Archyl zu einer Event-Quelle. Euer Architekturmodell wird zu etwas, das andere Systeme abonnieren, auf das sie reagieren und worauf sie aufbauen können.

Auslieferungsverfolgung

Jede Webhook-Auslieferung wird protokolliert. Ihr könnt die vollständige Historie für jeden Webhook einsehen: welches Event sie ausgelöst hat, den gesendeten Request-Payload, den Antwort-Statuscode, den Response-Body und die Zeitstempel für Sende- und Empfangszeitpunkt.

Auslieferungen werden sieben Tage lang aufbewahrt. Lang genug, um Integrationsprobleme zu debuggen, kurz genug, dass wir nicht die Response-Bodies eures Endpunkts auf unbestimmte Zeit speichern.

Wenn eine Auslieferung fehlschlägt — ein 500er von eurem Server, ein Timeout, ein DNS-Auflösungsfehler — wird sie mit einem roten Status angezeigt. Ihr könnt den Fehler untersuchen, euren Endpunkt reparieren und mit einem Klick erneut senden. Der Retry sendet exakt denselben Payload, sodass euer Endpunkt das ursprüngliche Event verarbeitet, als wäre es beim ersten Mal erfolgreich gewesen.

Keine automatischen Retries. Wir haben exponentielles Backoff in Betracht gezogen, aber in der Praxis sind die meisten Webhook-Fehler entweder vorübergehend (euer Server hat gerade neugestartet) oder strukturell (die URL ist falsch). Bei vorübergehenden Fehlern ist der manuelle Retry-Button schneller als auf Backoff zu warten. Bei strukturellen Fehlern erzeugen automatische Retries nur Rauschen.

Erste Schritte

Geht zu Organisationseinstellungen > Webhooks
Klickt auf Webhook erstellen
Gebt einen Namen ein, fügt eure Endpunkt-URL ein, setzt ein Secret
Wählt die Events aus, die ihr abonnieren möchtet
Filtert optional nach bestimmten Projekten
Klickt auf Test senden, um zu überprüfen, ob euer Endpunkt den Payload empfängt
Speichert, und ihr seid live

Die Testauslieferung sendet ein Ping-Event mit einem Beispiel-Payload, damit ihr bestätigen könnt, dass euer Endpunkt erreichbar ist, euer Secret korrekt konfiguriert ist und euer Handler das JSON wie erwartet verarbeitet. Macht das, bevor ihr echte Events abonniert.

Architektur als Event-Stream

Wir arbeiten auf eine Version von Architekturdokumentation hin, die kein statisches Artefakt ist — sondern ein lebendiger, vernetzter Teil eures Entwicklungsworkflows. Marketplace-Integrationen bringen externe Daten in eure Architektur. Webhooks pushen Architekturdaten hinaus zu euren Tools.

Die Kombination ist mächtig. Euer Architektur-Workspace ist nicht nur ein Ort, an dem ihr Diagramme anschaut. Es ist ein Hub, der operative Daten von euren Monitoring-Tools empfängt und Change-Events an eure Kommunikations- und Automatisierungstools sendet. Daten fließen in beide Richtungen.

Architekturdokumentation, die niemand anschaut, ist nutzlos. Architekturdokumentation, die euch benachrichtigt, wenn es darauf ankommt — das ist Infrastruktur.

Wollt ihr sehen, wie andere Features eure Architektur mit eurem Workflow verbinden? Schaut euch Marketplace-Integrationen an, um Live-Daten auf eure Diagramme zu bringen, oder Release-Management zur Verfolgung von Deployments über euer C4-Modell hinweg.