Notifiche Webhook

I webhook ti permettono di ricevere notifiche HTTP POST in tempo reale ogni volta che qualcosa cambia nel tuo workspace Archyl. Crea un webhook, indirizzalo al tuo URL, seleziona gli eventi che ti interessano e Archyl inviera una notifica al tuo endpoint ogni volta che quegli eventi si verificano.

Panoramica

Quando si verifica un evento -- un sistema viene creato, un rilascio viene distribuito, un ADR viene aggiornato -- Archyl invia una richiesta HTTP POST a ogni webhook iscritto a quell'evento. Il tuo endpoint riceve un payload JSON che descrive cosa e successo, chi l'ha fatto e a quale progetto appartiene.

Casi d'uso tipici:

• Notifiche Slack o Teams quando vengono apportate modifiche all'architettura
• Trigger CI/CD quando viene creato un nuovo rilascio
• Audit logging verso un sistema esterno
• Dashboard personalizzate che reagiscono agli eventi dell'architettura
• Pipeline di automazione che si attivano al completamento delle discovery

Eventi Supportati

Elementi di Architettura

Gestione dei Progetti

Documentazione

Collaborazione e Analisi

Creazione di un Webhook

1. Vai in Impostazioni Organizzazione e seleziona la scheda Webhook
2. Clicca su Nuovo Webhook
3. Compila la configurazione:

4. Clicca su Crea

Il webhook inizia a ricevere eventi immediatamente.

Formato del Payload

Ogni consegna webhook invia un payload JSON con questa struttura:

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

L'header Content-Type e sempre application/json.

Sicurezza

Header della Richiesta

Ogni consegna webhook include questi header:

Verifica della Firma HMAC-SHA256

Se imposti un token segreto al momento della creazione del webhook, Archyl firma ogni payload usando HMAC-SHA256. La firma viene inviata nell'header X-Archyl-Signature con il formato:

sha256=<digest HMAC-SHA256 codificato in esadecimale>

Per verificare una consegna:

1. Leggi il corpo grezzo della richiesta (i byte esatti, prima di qualsiasi parsing JSON)
2. Leggi l'header X-Archyl-Signature e rimuovi il prefisso sha256= per ottenere la firma esadecimale
3. Calcola un hash HMAC-SHA256 del corpo grezzo usando il tuo token segreto come chiave
4. Codifica il risultato in esadecimale e confrontalo con la firma ottenuta al passo 2 usando un confronto a tempo costante
5. Rifiuta la richiesta se non corrispondono

Esempio in 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
}

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

Esempio in 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)

Usa sempre un confronto a tempo costante (hmac.Equal, crypto.timingSafeEqual, hmac.compare_digest) per prevenire attacchi di tipo timing. Verifica sempre rispetto al corpo grezzo della richiesta -- il parsing e la ri-serializzazione del JSON possono modificare la rappresentazione in byte e invalidare la firma.

Storico delle Consegne

Ogni webhook mantiene un registro delle consegne recenti. Per visualizzarlo:

1. Vai in Impostazioni Organizzazione > Webhook
2. Clicca sul nome del webhook
3. Apri la scheda Consegne

Ogni voce di consegna mostra:

Le consegne vengono conservate per 7 giorni. Dopo tale periodo, vengono eliminate automaticamente.

Un badge verde indica una consegna riuscita (risposta 2xx). Il rosso indica un errore (risposta non-2xx o timeout).

Test

Prima di fare affidamento su un webhook in produzione, verifica che funzioni:

1. Apri la pagina di dettaglio del webhook
2. Clicca su Invia Test
3. Archyl invia un payload di test al tuo endpoint con event: "webhook.test"
4. Controlla la scheda Consegne per confermare la ricezione e ispezionare la risposta

La consegna di test utilizza lo stesso meccanismo di firma degli eventi reali, cosi puoi validare la tua logica di verifica della firma contemporaneamente.

Politica di Retry

Quando una consegna fallisce (risposta non-2xx o timeout di rete), Archyl riprova automaticamente:

Dopo 3 retry falliti, la consegna viene contrassegnata come non riuscita. Puoi riattivare manualmente qualsiasi consegna fallita dalla scheda Consegne cliccando su Riprova.

Se un webhook fallisce costantemente per 24 ore, Archyl lo disabilita e invia una notifica agli amministratori dell'organizzazione. Riabilitalo dalle impostazioni del webhook una volta risolto il problema.

Filtraggio per Progetti

Per impostazione predefinita, un webhook riceve eventi da tutti i progetti dell'organizzazione. Per restringere l'ambito:

1. Modifica il webhook
2. Sotto Progetti, seleziona uno o piu progetti
3. Salva

Solo gli eventi provenienti dai progetti selezionati attiveranno le consegne. Questo e utile quando team diversi gestiscono progetti diversi e necessitano di notifiche solo per il proprio lavoro.

Puoi aggiornare il filtro per progetto in qualsiasi momento senza dover ricreare il webhook.

Buone Pratiche

Rispondi Rapidamente

Il tuo endpoint dovrebbe restituire una risposta 2xx entro 10 secondi. Se hai bisogno di elaborazioni pesanti, accetta il webhook immediatamente e gestisci il lavoro in modo asincrono in un job in background.

Verifica le Firme

Imposta sempre un token segreto e verifica l'header X-Archyl-Signature. Questo garantisce che i payload provengano realmente da Archyl e non siano stati manomessi.

Usa HTTPS

Utilizza sempre un endpoint HTTPS. Archyl non consegnera webhook a URL HTTP non cifrati.

Filtra per Progetto

Se la tua organizzazione ha molti progetti, limita i webhook ai progetti che ti interessano. Questo riduce il rumore ed evita elaborazioni inutili da parte tua.

Gestisci i Duplicati

In rari casi (retry di rete, failover dell'infrastruttura), il tuo endpoint potrebbe ricevere lo stesso evento piu di una volta. Usa i campi timestamp e event per rilevare e deduplicare.

Monitora lo Stato delle Consegne

Controlla periodicamente la scheda Consegne. Un pattern di errori potrebbe indicare problemi con l'endpoint, regole del firewall o credenziali scadute da parte tua.

Prossimi Passi

• Integrazioni Marketplace -- Connetti servizi esterni e visualizza dati in tempo reale sulle tue dashboard
• Gestione dei Rilasci -- Monitora i deployment nella tua architettura
• Insight sull'Architettura -- Rileva automaticamente problemi architetturali