Notifications Webhook

Les webhooks vous permettent de recevoir des notifications HTTP POST en temps réel chaque fois que quelque chose change dans votre espace Archyl. Créez un webhook, pointez-le vers votre URL, sélectionnez les événements qui vous intéressent, et Archyl notifiera votre endpoint à chaque déclenchement.

Vue d'ensemble

Lorsqu'un événement se produit — un système est créé, une release est déployée, un ADR est mis à jour — Archyl envoie une requête HTTP POST à chaque webhook abonné à cet événement. Votre endpoint reçoit un payload JSON décrivant ce qui s'est passé, qui l'a fait, et à quel projet cela appartient.

Cas d'utilisation courants :

• Notifications Slack ou Teams lorsque des changements d'architecture sont effectués
• Déclencheurs CI/CD lors de la création d'une nouvelle release
• Journalisation d'audit vers un système externe
• Tableaux de bord personnalisés qui réagissent aux événements d'architecture
• Pipelines d'automatisation qui s'exécutent à la fin des découvertes

Événements Supportés

Éléments d'Architecture

Gestion de Projet

Documentation

Collaboration et Analyse

Créer un Webhook

1. Allez dans les Paramètres de l'organisation et sélectionnez l'onglet Webhooks
2. Cliquez sur Nouveau Webhook
3. Remplissez la configuration :

4. Cliquez sur Créer

Le webhook commence à recevoir des événements immédiatement.

Format du Payload

Chaque livraison de webhook envoie un payload JSON avec cette structure :

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

Le header Content-Type est toujours application/json.

Sécurité

Headers de Requête

Chaque livraison de webhook inclut ces headers :

Vérification de Signature HMAC-SHA256

Si vous définissez un token secret lors de la création du webhook, Archyl signe chaque payload avec HMAC-SHA256. La signature est envoyée dans le header X-Archyl-Signature avec le format :

sha256=<digest HMAC-SHA256 encodé en hexadécimal>

Pour vérifier une livraison :

1. Lisez le corps brut de la requête (les octets exacts, avant tout parsing JSON)
2. Lisez le header X-Archyl-Signature et retirez le préfixe sha256= pour obtenir la signature hexadécimale
3. Calculez un hash HMAC-SHA256 du corps brut en utilisant votre token secret comme clé
4. Encodez le résultat en hexadécimal et comparez-le à la signature de l'étape 2 en utilisant une comparaison en temps constant
5. Rejetez la requête si les valeurs ne correspondent pas

Exemple Go :

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
}

Exemple Node.js :

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);
}

Exemple Python :

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)

Utilisez toujours une comparaison en temps constant (hmac.Equal, crypto.timingSafeEqual, hmac.compare_digest) pour prévenir les attaques par timing. Vérifiez toujours contre le corps brut de la requête -- parser et re-sérialiser le JSON peut modifier la représentation en octets et invalider la signature.

Historique des Livraisons

Chaque webhook conserve un journal des livraisons récentes. Pour le consulter :

1. Allez dans Paramètres de l'organisation > Webhooks
2. Cliquez sur le nom du webhook
3. Ouvrez l'onglet Livraisons

Chaque entrée de livraison affiche :

Les livraisons sont conservées pendant 7 jours. Après cette période, elles sont automatiquement purgées.

Un badge vert indique une livraison réussie (réponse 2xx). Un badge rouge indique un échec (réponse non-2xx ou timeout).

Test

Avant de vous fier à un webhook en production, vérifiez qu'il fonctionne :

1. Ouvrez la page de détail du webhook
2. Cliquez sur Envoyer un Test
3. Archyl envoie un payload de test à votre endpoint avec event: "webhook.test"
4. Vérifiez l'onglet Livraisons pour confirmer la réception et inspecter la réponse

La livraison de test utilise le même mécanisme de signature que les événements réels, vous pouvez donc valider votre logique de vérification de signature en même temps.

Politique de Retry

Lorsqu'une livraison échoue (réponse non-2xx ou timeout réseau), Archyl effectue automatiquement des retentatives :

Après 3 retentatives échouées, la livraison est marquée comme échouée. Vous pouvez relancer manuellement toute livraison échouée depuis l'onglet Livraisons en cliquant sur Réessayer.

Si un webhook échoue de manière continue pendant 24 heures, Archyl le désactive et envoie une notification aux administrateurs de l'organisation. Réactivez-le depuis les paramètres du webhook une fois le problème résolu.

Filtrage par Projets

Par défaut, un webhook reçoit les événements de tous les projets de l'organisation. Pour restreindre le périmètre :

1. Modifiez le webhook
2. Sous Projets, sélectionnez un ou plusieurs projets
3. Enregistrez

Seuls les événements provenant des projets sélectionnés déclencheront des livraisons. C'est utile lorsque différentes équipes gèrent différents projets et n'ont besoin de notifications que pour leur propre travail.

Vous pouvez mettre à jour le filtre de projets à tout moment sans recréer le webhook.

Bonnes Pratiques

Répondez Rapidement

Votre endpoint doit retourner une réponse 2xx en moins de 10 secondes. Si vous avez besoin d'effectuer un traitement lourd, acceptez le webhook immédiatement et traitez le travail de manière asynchrone dans une tâche en arrière-plan.

Vérifiez les Signatures

Définissez toujours un token secret et vérifiez le header X-Archyl-Signature. Cela garantit que les payloads proviennent bien d'Archyl et n'ont pas été altérés.

Utilisez HTTPS

Utilisez toujours un endpoint HTTPS. Archyl ne livrera pas de webhooks vers des URLs HTTP non sécurisées.

Filtrez par Projet

Si votre organisation a de nombreux projets, limitez les webhooks aux projets qui vous concernent. Cela réduit le bruit et évite les traitements inutiles de votre côté.

Gérez les Doublons

Dans de rares cas (retentatives réseau, basculement d'infrastructure), votre endpoint peut recevoir le même événement plus d'une fois. Utilisez les champs timestamp et event pour détecter et dédupliquer.

Surveillez la Santé des Livraisons

Consultez l'onglet Livraisons périodiquement. Un schéma d'échecs récurrents peut indiquer des problèmes d'endpoint, des règles de pare-feu ou des identifiants expirés de votre côté.

Prochaines Étapes

• Intégrations Marketplace — Connectez des services externes et affichez des données en temps réel sur vos tableaux de bord
• Gestion des Releases — Suivez les déploiements à travers votre architecture
• Insights d'Architecture — Détectez les problèmes architecturaux automatiquement