Webhook che non si fidano di nessuno (e non perdono nulla)

Perché un'integrazione fragile costa più di quello che fa risparmiare

Un'integrazione fragile spesso non si rompe in modo rumoroso. Una richiesta si perde, una risposta arriva a metà, una pratica resta ferma e nessuno se ne accorge finché un cliente non chiede notizie. Il costo di quel silenzio supera in fretta il tempo che l'automazione prometteva di far risparmiare.

Per questo gli eventi di FlowSharp, che ora dialogano con i sistemi esterni in entrambe le direzioni, sono costruiti attorno ai dettagli: firme, limiti, storico delle consegne, retry che non duplicano e un'uscita di sicurezza affidata a una persona. È lo stesso principio del nostro metodo, prima misura, poi automatizza: un collegamento che non si riesce a osservare non si riesce nemmeno a migliorare.

Questo articolo non riguarda la divisione dei ruoli tra n8n e FlowSharp, di cui parla «n8n come motore di integrazione, FlowSharp come governo». Qui il tema è un altro: quanto è robusto il collegamento stesso.

Webhook in ingresso: un indirizzo per sistema, firmato e con storico

Ogni evento di tipo Custom o External può avere uno o più webhook in ingresso, uno per ciascun sistema esterno. Chi chiama l'indirizzo con il segreto fa scattare l'evento, che si comporta come qualsiasi altro evento di FlowSharp: avvisa i sottoscrittori e può avviare pratiche. Non servono chiavi API.

Le chiamate sono firmate per default. Indirizzo e segreto vengono mostrati una sola volta, insieme a un esempio pronto da copiare: conviene salvarli nel gestore di segreti del sistema chiamante già in quel momento. Avere un webhook per sistema permette di distinguere chi sta chiamando e di intervenire su un collegamento senza toccare gli altri.

Ogni ricezione resta nello storico, senza il contenuto della chiamata. Lo storico si svuota da solo dopo 10 giorni, periodo che si può modificare per organizzazione. Se arriva una raffica di chiamate oltre il limite, lo storico non si riempie di righe: ne resta una al minuto per webhook, sufficiente a capire che è successo senza trasformare il problema in rumore.

Il tetto di banda per organizzazione sui webhook in ingresso conta i byte effettivamente ricevuti, non quelli dichiarati dal mittente. I rifiuti anticipati chiudono subito la connessione. Un mittente che dichiara poco e invia molto non aggira il limite.

Per chi amministra, tutto sta in un punto: in Impostazioni > Webhook l'Admin trova tutti i webhook con le ultime ricezioni.

Webhook in uscita: form guidato, prova immediata, consegne tracciate

Sul fronte opposto, i sottoscrittori Webhook e n8n non si configurano più scrivendo un JSON, ma con un form guidato: indirizzo, metodo, intestazioni. Meno campi liberi significa meno errori di battitura scoperti solo alla prima consegna reale. Le chiamate in uscita sono firmate per default, così il sistema che le riceve può verificare da chi arrivano.

Il pulsante «Invia una prova» fa partire una chiamata di test e mostra subito l'esito. Si capisce prima di andare in produzione se l'indirizzo risponde e se le intestazioni sono quelle attese.

Ogni consegna resta nello storico, e la scheda «In uscita» di Impostazioni > Webhook elenca tutti i sottoscrittori di questo tipo. Per chi crea webhook in uscita via API vale la stessa regola: i nuovi sono firmati per default, e la firma si può disattivare solo esplicitamente al momento della creazione. I webhook già esistenti conservano la propria impostazione, quindi vale la pena controllarli se li avete creati prima di questo cambio.

Anche lo stato dell'evento dice di più. Un evento resta in corso finché ci sono consegne da completare o da ritentare, e distingue tra consegne riuscite, fallimenti definitivi e invii saltati. Una consegna che esaurisce i tentativi senza esito viene chiusa come fallita, con un motivo leggibile. Non resta in sospeso in attesa di qualcuno che la noti.

Retry che non duplicano: transizioni e import di mappe

Il problema classico di ogni integrazione è la risposta che non arriva. Il chiamante non sa se la richiesta è stata eseguita, e ripeterla rischia di eseguirla due volte. FlowSharp affronta il caso in due punti.

Sulle transizioni di fase, un'integrazione che non riceve una risposta chiara può ripetere la richiesta dichiarando da quale fase pensava di partire. Se nel frattempo la pratica è già altrove, il retry si ferma senza alcun effetto: non sposta la pratica una seconda volta. Se invece una transizione manuale arriva mentre una fase sta ancora entrando, riceve un errore ritentabile, che di norma si risolve in pochi secondi. È un segnale di riprovare, non un fallimento.

Per l'import di mappe via API vale un principio analogo. Con una chiave di richiesta, la ripetizione di una richiesta già conclusa è riconoscibile e non crea una seconda mappa. Per chi automatizza il rilascio dei processi tra ambienti, significa poter rilanciare uno script interrotto senza ritrovarsi con copie doppie da ripulire.

In entrambi i casi il chiamante può ripetere con più serenità, perché il sistema sa distinguere una richiesta nuova da una già gestita.

Il ripiego umano: quando l'automazione deve passare la mano

Nessuna firma o retry risolve il caso in cui il sistema esterno risponde, ma con qualcosa che il processo non sa gestire. Per questo un task Integrazione può chiedere l'intervento di una persona in tre situazioni: dopo un errore permanente, dopo i tentativi previsti, oppure quando la risposta non è tra gli esiti automatici attesi.

Il lavoro compare nella stessa coda di tutti gli altri, con il badge Ripiego. Non c'è una console separata da controllare: chi lavora le pratiche lo vede dove già guarda. La persona decide sul task originale, quindi la decisione resta legata al punto del processo in cui è nata. I dati della risposta scartata non vengono applicati, perché una risposta inattesa non entra nella pratica senza che qualcuno l'abbia valutata.

Per i responsabili IT e operations il risultato è concreto: meno pratiche ferme in silenzio. Le anomalie previste finiscono o in uno stato chiuso con un motivo leggibile, o davanti a una persona che può decidere.

Per chi integra, il punto di partenza è semplice: attivare le firme, provare il collegamento con «Invia una prova», e controllare in Impostazioni > Webhook cosa è arrivato e cosa è partito.