Webhook-Benachrichtigungen

Webhooks ermöglichen es Ihnen, HTTP-POST-Benachrichtigungen in Echtzeit zu erhalten, sobald sich etwas in Ihrem Archyl-Workspace ändert. Erstellen Sie einen Webhook, geben Sie Ihre URL an, wählen Sie die gewünschten Events aus, und Archyl benachrichtigt Ihren Endpoint bei jedem Auftreten dieser Events.

Überblick

Wenn ein Event eintritt — ein System wird erstellt, ein Release deployed, ein ADR aktualisiert — sendet Archyl eine HTTP-POST-Anfrage an jeden Webhook, der dieses Event abonniert hat. Ihr Endpoint erhält einen JSON-Payload, der beschreibt, was passiert ist, wer es ausgelöst hat und zu welchem Projekt es gehört.

Typische Anwendungsfälle:

• Slack- oder Teams-Benachrichtigungen bei Architekturänderungen
• CI/CD-Auslöser bei Erstellung eines neuen Releases
• Audit-Logging an ein externes System
• Benutzerdefinierte Dashboards, die auf Architektur-Events reagieren
• Automatisierungs-Pipelines, die nach Abschluss von Discoveries ausgeführt werden

Unterstützte Events

Architekturelemente

Projektverwaltung

Dokumentation

Zusammenarbeit & Analyse

Einen Webhook Erstellen

1. Gehen Sie zu den Organisationseinstellungen und wählen Sie den Tab Webhooks
2. Klicken Sie auf Neuer Webhook
3. Füllen Sie die Konfiguration aus:

4. Klicken Sie auf Erstellen

Der Webhook empfängt sofort Events.

Payload-Format

Jede Webhook-Zustellung sendet einen JSON-Payload mit folgender Struktur:

{
  "event": "system.created",
  "timestamp": "2026-03-10T14:30:00Z",
  "data": {
    "entityType": "system",
    "entityName": "Payment Service",
    "action": "created",
    "userName": "vincent",
    "projectId": "a1b2c3d4-...",
    "projectName": "My Project"
  }
}

Der Content-Type-Header ist immer application/json.

Sicherheit

Anfrage-Header

Jede Webhook-Zustellung enthält folgende Header:

HMAC-SHA256-Signaturverifikation

Wenn Sie beim Erstellen des Webhooks ein Secret Token festlegen, signiert Archyl jeden Payload mit HMAC-SHA256. Die Signatur wird im X-Archyl-Signature-Header im folgenden Format gesendet:

sha256=<hex-encoded HMAC-SHA256 digest>

So verifizieren Sie eine Zustellung:

1. Lesen Sie den rohen Request-Body (die exakten Bytes, vor jeglichem JSON-Parsing)
2. Lesen Sie den X-Archyl-Signature-Header und entfernen Sie das Präfix sha256=, um die Hex-Signatur zu erhalten
3. Berechnen Sie einen HMAC-SHA256-Hash des rohen Bodys mit Ihrem Secret Token als Schlüssel
4. Kodieren Sie das Ergebnis als Hex-String und vergleichen Sie es mit der Signatur aus Schritt 2 mittels eines zeitkonstanten Vergleichs
5. Lehnen Sie die Anfrage ab, wenn die Werte nicht übereinstimmen

Go-Beispiel:

func verifyArchylWebhook(r *http.Request, secret string) ([]byte, error) {
    body, err := io.ReadAll(r.Body)
    if err != nil {
        return nil, err
    }

    header := r.Header.Get("X-Archyl-Signature")
    if !strings.HasPrefix(header, "sha256=") {
        return nil, fmt.Errorf("missing or invalid signature header")
    }
    signature := strings.TrimPrefix(header, "sha256=")

    mac := hmac.New(sha256.New, []byte(secret))
    mac.Write(body)
    expected := hex.EncodeToString(mac.Sum(nil))

    if !hmac.Equal([]byte(expected), []byte(signature)) {
        return nil, fmt.Errorf("signature mismatch")
    }
    return body, nil
}

Node.js-Beispiel:

const crypto = require("crypto");

function verifyArchylWebhook(req, secret) {
  const header = req.headers["x-archyl-signature"] || "";
  if (!header.startsWith("sha256=")) {
    throw new Error("Missing or invalid signature header");
  }
  const signature = header.slice("sha256=".length);

  const body = req.rawBody; // use raw body, not parsed JSON
  const expected = crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");

  if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) {
    throw new Error("Signature mismatch");
  }
  return JSON.parse(body);
}

Python-Beispiel:

import hmac
import hashlib

def verify_archyl_webhook(body: bytes, header: str, secret: str) -> dict:
    if not header.startswith("sha256="):
        raise ValueError("Missing or invalid signature header")
    signature = header.removeprefix("sha256=")

    expected = hmac.new(
        secret.encode(), body, hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, signature):
        raise ValueError("Signature mismatch")
    return json.loads(body)

Verwenden Sie immer einen zeitkonstanten Vergleich (hmac.Equal, crypto.timingSafeEqual, hmac.compare_digest), um Timing-Angriffe zu verhindern. Verifizieren Sie stets gegen den rohen Request-Body -- das Parsen und erneute Serialisieren von JSON kann die Byte-Darstellung verändern und die Signatur ungültig machen.

Zustellungshistorie

Jeder Webhook führt ein Protokoll der letzten Zustellungen. So zeigen Sie es an:

1. Gehen Sie zu Organisationseinstellungen > Webhooks
2. Klicken Sie auf den Webhook-Namen
3. Öffnen Sie den Tab Zustellungen

Jeder Zustellungseintrag zeigt:

Zustellungen werden 7 Tage aufbewahrt. Danach werden sie automatisch gelöscht.

Ein grünes Badge zeigt eine erfolgreiche Zustellung an (2xx-Antwort). Rot zeigt einen Fehler an (nicht-2xx oder Timeout).

Testen

Bevor Sie sich in der Produktion auf einen Webhook verlassen, überprüfen Sie seine Funktion:

1. Öffnen Sie die Webhook-Detailseite
2. Klicken Sie auf Test senden
3. Archyl sendet einen Test-Payload an Ihren Endpoint mit event: "webhook.test"
4. Prüfen Sie den Zustellungen-Tab, um den Empfang zu bestätigen und die Antwort zu inspizieren

Die Testzustellung verwendet denselben Signierungsmechanismus wie echte Events, sodass Sie gleichzeitig Ihre Signaturverifikationslogik validieren können.

Retry-Richtlinie

Wenn eine Zustellung fehlschlägt (nicht-2xx-Antwort oder Netzwerk-Timeout), wiederholt Archyl automatisch:

Nach 3 fehlgeschlagenen Wiederholungen wird die Zustellung als fehlgeschlagen markiert. Sie können jede fehlgeschlagene Zustellung im Zustellungen-Tab manuell erneut auslösen, indem Sie auf Wiederholen klicken.

Wenn ein Webhook durchgehend 24 Stunden lang fehlschlägt, deaktiviert Archyl ihn und sendet eine Benachrichtigung an die Organisationsadministratoren. Aktivieren Sie ihn in den Webhook-Einstellungen erneut, sobald das Problem behoben ist.

Filterung nach Projekten

Standardmäßig empfängt ein Webhook Events aus allen Projekten der Organisation. Um den Bereich einzuschränken:

1. Bearbeiten Sie den Webhook
2. Wählen Sie unter Projekte ein oder mehrere Projekte aus
3. Speichern Sie

Nur Events aus den ausgewählten Projekten lösen Zustellungen aus. Dies ist nützlich, wenn verschiedene Teams verschiedene Projekte verwalten und nur Benachrichtigungen für ihre eigene Arbeit benötigen.

Sie können den Projektfilter jederzeit aktualisieren, ohne den Webhook neu erstellen zu müssen.

Best Practices

Antworten Sie Schnell

Ihr Endpoint sollte innerhalb von 10 Sekunden eine 2xx-Antwort zurückgeben. Wenn Sie aufwendige Verarbeitung durchführen müssen, nehmen Sie den Webhook sofort an und verarbeiten Sie die Arbeit asynchron in einem Hintergrund-Job.

Signaturen Verifizieren

Legen Sie immer ein Secret Token fest und verifizieren Sie den X-Archyl-Signature-Header. Dies stellt sicher, dass Payloads tatsächlich von Archyl stammen und nicht manipuliert wurden.

HTTPS Verwenden

Verwenden Sie immer einen HTTPS-Endpoint. Archyl liefert keine Webhooks an unverschlüsselte HTTP-URLs aus.

Nach Projekt Filtern

Wenn Ihre Organisation viele Projekte hat, beschränken Sie Webhooks auf die Projekte, die Sie interessieren. Dies reduziert Rauschen und vermeidet unnötige Verarbeitung auf Ihrer Seite.

Duplikate Behandeln

In seltenen Fällen (Netzwerk-Wiederholungen, Infrastruktur-Failover) kann Ihr Endpoint dasselbe Event mehr als einmal erhalten. Verwenden Sie die Felder timestamp und event, um Duplikate zu erkennen und zu deduplizieren.

Zustellungsstatus Überwachen

Überprüfen Sie regelmäßig den Zustellungen-Tab. Ein Muster von Fehlern kann auf Endpoint-Probleme, Firewall-Regeln oder abgelaufene Anmeldedaten auf Ihrer Seite hinweisen.

Nächste Schritte

• Marketplace-Integrationen — Verbinden Sie externe Dienste und zeigen Sie Live-Daten auf Ihren Dashboards an
• Release-Management — Verfolgen Sie Deployments über Ihre Architektur
• Architektur-Insights — Erkennen Sie architektonische Probleme automatisch