Webhooks: Notifiche in Tempo Reale per i Cambiamenti Architetturali
La settimana scorsa un team mi ha raccontato di aver rinominato un sistema centrale in Archyl — cambiato "UserService" in "AccountService" in tutto il modello C4, aggiornato le relazioni, riscritto l'ADR. Un lavoro pulito e accurato. Il problema? Il team di piattaforma che dipendeva da quel sistema lo ha scoperto quattro giorni dopo, quando la loro pipeline di deployment faceva riferimento a un nome che non esisteva più.
Nessuno li aveva avvisati. Non perché qualcuno fosse stato negligente — semplicemente non esisteva un meccanismo per farlo. La documentazione architetturale è tipicamente un modello pull. Vai a guardare il diagramma. Vai a leggere l'ADR. Se non vai a controllare, non lo sai.
È lo stesso schema che affliggeva lo sviluppo software prima che le notifiche CI/CD diventassero standard. Le modifiche al codice erano qualcosa che scoprivi quando facevi pull di main. Oggi, ogni merge, ogni build fallita, ogni deploy genera una notifica da qualche parte. I cambiamenti architetturali meritano lo stesso trattamento.
Notifiche Push per la Tua Architettura
Archyl ora supporta i webhooks. Quando qualcosa cambia nel tuo modello C4 — un sistema viene creato, un container viene eliminato, una relazione viene aggiornata, una release va in produzione — Archyl invia un HTTP POST a qualsiasi endpoint configurato, con un payload JSON che descrive esattamente cosa è successo.
Il concetto è semplice: la tua architettura è un sistema vivente. Persone e strumenti dovrebbero potersi iscrivere ai suoi cambiamenti nello stesso modo in cui si iscrivono agli eventi di deploy o alle notifiche delle pull request. Invece di chiederti "è cambiato qualcosa?", la risposta arriva da sola.
44 Tipi di Evento
Non volevamo rilasciare un sistema di notifiche che coprisse solo metà del modello. I webhooks si attivano su tutto ciò che Archyl traccia:
Elementi C4 — Creazione, aggiornamento ed eliminazione di system, container, component e code element. Il cuore del tuo modello architetturale.
Relazioni — Quando le connessioni tra elementi vengono create, modificate o rimosse. Questo è spesso il segnale più importante — una nuova dipendenza tra due sistemi è il tipo di cambiamento che più team devono conoscere.
ADR e Documentazione — Architecture Decision Record e documenti di progetto creati, aggiornati o eliminati. Quando qualcuno scrive un nuovo ADR che spiega perché il team sta migrando da REST a gRPC, le persone coinvolte dovrebbero saperlo subito, non tre sprint dopo.
Flussi — Modifiche ai flussi utente e di sistema. Nuovi flussi, passaggi aggiornati, flussi eliminati.
Overlay — Modifiche ai raggruppamenti visivi nei tuoi diagrammi.
Release — Eventi di deployment attraverso gli ambienti. Combinato con la gestione delle release, questo ti offre una pipeline completa di notifiche push per i deployment.
Richieste — Richieste di modifica architetturale aperte, revisionate o approvate.
API Contract ed Event Channel — Modifiche alle specifiche e aggiornamenti alla messaggistica asincrona collegati alla tua architettura.
Discovery e Insight — Completamento delle discovery basate su IA e nuovi insight architetturali.
Quarantaquattro tipi di evento in totale. Scegli quelli che ti interessano — iscriviti a tutto, oppure solo ai cinque eventi che contano per il tuo workflow.
Come Funziona
Configurare un webhook richiede circa trenta secondi.
Gli dai un nome (qualcosa di descrittivo — "Notifiche Slack", "Sync audit log", "Trigger CI"). Fornisci un URL — qualsiasi endpoint HTTP che possa ricevere una richiesta POST. Opzionalmente imposti un secret per la verifica della firma. Poi scegli quali eventi devono attivarlo.
Puoi anche limitare un webhook a progetti specifici. Un webhook a livello di organizzazione che si attiva per ogni modifica su ogni progetto è utile per l'audit logging. Un webhook limitato a un progetto che si attiva solo sugli eventi di release del tuo sistema di pagamento è utile per il team che lo gestisce.
Quando si verifica un evento corrispondente, Archyl invia un HTTP POST al tuo URL con un payload JSON contenente:
- Tipo di evento — Quale dei 44 eventi ha attivato questa consegna
- Entità — I dettagli completi dell'elemento che è cambiato
- Attore — Chi ha effettuato la modifica (ID utente, nome, email)
- Progetto — In quale progetto è avvenuto
- Timestamp — Quando è avvenuta la modifica
- Organizzazione — A quale organizzazione appartiene
Il payload ti fornisce tutto il necessario per reagire al cambiamento — visualizzarlo, registrarlo, attivare una pipeline o sincronizzarlo con un altro sistema.
Sicurezza: Firme HMAC-SHA256
Ogni richiesta webhook include un header X-Archyl-Signature con il formato sha256=<hex digest> — un hash HMAC-SHA256 del corpo grezzo della richiesta, calcolato usando il tuo secret. Riceverai anche X-Archyl-Event (il tipo di evento) e User-Agent: Archyl-Webhook/1.0 per identificare la sorgente.
Lato ricevente, rimuovi il prefisso sha256=, ricalcoli l'hash HMAC-SHA256 con la tua copia del secret sui byte grezzi del corpo e confronti usando un confronto a tempo costante. Se corrispondono, la richiesta è autentica. Se non corrispondono, qualcuno ti sta inviando eventi contraffatti.
È lo stesso schema di firma usato da GitHub, Stripe e dalla maggior parte dei provider di webhook. È semplice, ben conosciuto e facile da implementare in qualsiasi linguaggio. Nessun flusso OAuth, nessuna rotazione di token, nessuna gestione di certificati. Solo un secret condiviso e un hash. Consulta la documentazione webhook per esempi completi di verifica in Go, Node.js e Python.
Se non imposti un secret, l'header della firma viene omesso. Va bene per endpoint interni dietro una VPN. Non raccomandato per qualsiasi cosa esposta a internet.
Cosa Puoi Costruire Con Questo
Il caso d'uso più ovvio sono le notifiche chat. Slack, Microsoft Teams e Discord supportano tutti i webhook in ingresso — incolla il loro URL in Archyl, seleziona gli eventi che ti interessano, e i cambiamenti architetturali iniziano ad apparire nel tuo canale. Un nuovo sistema è stato aggiunto. Un ADR è stato approvato. Una release è andata in produzione. Il tuo team lo vede senza aprire Archyl.
Ma le notifiche sono solo l'inizio.
Sincronizzazione con sistemi esterni — Invia i cambiamenti architetturali a un CMDB, un wiki interno o un catalogo dei servizi. Quando un container viene rinominato in Archyl, il tuo catalogo dei servizi si aggiorna automaticamente.
Attivazione di pipeline CI/CD — Quando una richiesta di modifica architetturale viene approvata, avvia una pipeline che rigenera la configurazione dell'infrastruttura, aggiorna i moduli Terraform o verifica che il deployment effettivo corrisponda all'architettura documentata.
Traccia di audit — Inoltra ogni evento a un sistema di logging esterno — Elasticsearch, Splunk, un semplice database append-only. Sette giorni di storico delle consegne in Archyl sono utili per il debug; un log esterno permanente è utile per la compliance.
Dashboard personalizzate — Costruisci una dashboard interna che reagisce agli eventi architetturali in tempo reale. Monitora quanto spesso l'architettura cambia, quali team sono più attivi, quali sistemi sono più volatili.
Il punto è che i webhooks trasformano Archyl in una sorgente di eventi. Il tuo modello architetturale diventa qualcosa a cui altri sistemi possono iscriversi, reagire e su cui costruire.
Tracciamento delle Consegne
Ogni consegna webhook viene registrata. Puoi vedere lo storico completo per qualsiasi webhook: quale evento l'ha attivato, il payload della richiesta inviato, il codice di stato della risposta, il corpo della risposta e i timestamp di quando è stato inviato e quando è arrivata la risposta.
Le consegne vengono conservate per sette giorni. Abbastanza a lungo per risolvere problemi di integrazione, abbastanza breve per non conservare i corpi delle risposte del tuo endpoint a tempo indefinito.
Quando una consegna fallisce — un 500 dal tuo server, un timeout, un errore di risoluzione DNS — appare con uno stato rosso. Puoi ispezionare l'errore, correggere il tuo endpoint e riprovare con un clic. Il retry invia esattamente lo stesso payload, così il tuo endpoint processa l'evento originale come se fosse riuscito la prima volta.
Nessun retry automatico. Abbiamo valutato l'exponential backoff, ma nella pratica la maggior parte dei fallimenti webhook sono o transitori (il tuo server si stava riavviando) o strutturali (l'URL è sbagliato). Per i fallimenti transitori, il pulsante di retry manuale è più veloce dell'attesa del backoff. Per i fallimenti strutturali, i retry automatici generano solo rumore.
Per Iniziare
- Vai su Impostazioni Organizzazione > Webhooks
- Clicca Crea Webhook
- Inserisci un nome, incolla l'URL del tuo endpoint, imposta un secret
- Seleziona gli eventi a cui vuoi iscriverti
- Opzionalmente filtra per progetti specifici
- Clicca Invia Test per verificare che il tuo endpoint riceva il payload
- Salva, e sei operativo
La consegna di test invia un evento ping con un payload di esempio, così puoi confermare che il tuo endpoint è raggiungibile, il tuo secret è configurato correttamente e il tuo handler processa il JSON come previsto. Fallo prima di iscriverti agli eventi reali.
L'Architettura come Flusso di Eventi
Stiamo costruendo verso una versione della documentazione architetturale che non è un artefatto statico — è una parte viva e connessa del tuo workflow di sviluppo. Le Integrazioni Marketplace portano dati esterni dentro la tua architettura. I webhooks inviano dati architetturali fuori verso i tuoi strumenti.
La combinazione è potente. Il tuo workspace architetturale non è solo un posto dove vai a guardare diagrammi. È un hub che riceve dati operativi dai tuoi strumenti di monitoraggio ed emette eventi di cambiamento verso i tuoi strumenti di comunicazione e automazione. I dati fluiscono in entrambe le direzioni.
La documentazione architetturale che nessuno guarda è inutile. La documentazione architetturale che ti notifica quando conta — quella è infrastruttura.
Vuoi vedere come altre funzionalità collegano la tua architettura al tuo workflow? Scopri le Integrazioni Marketplace per portare dati live sui tuoi diagrammi, o la Gestione delle Release per tracciare i deployment attraverso il tuo modello C4.