🇮🇹 IT

🔗 Webhook Trigger

Il Webhook Trigger avvia un'esecuzione del workflow ogni volta che viene ricevuta una richiesta HTTP POST all'URL webhook univoco del workflow. È il punto di integrazione più comune tra Flusso e le applicazioni esterne, consentendo a qualsiasi sistema capace di inviare richieste HTTP di avviare un workflow e passargli dati in tempo reale.

Categoria: Trigger · Identificatore tipo: webhook_trigger

Panoramica

Ogni workflow che utilizza un Webhook Trigger viene assegnato un URL permanente e univoco. Quando un servizio esterno — come un processore di pagamenti, un form builder, un CRM o qualsiasi applicazione personalizzata — invia una richiesta HTTP POST a quell'URL, Flusso avvia il workflow immediatamente. Il corpo completo della richiesta, gli header e il metodo HTTP vengono tutti catturati e resi disponibili ai passaggi successivi come variabili di output.

Il Webhook Trigger non fa assunzioni sulla forma dei dati in arrivo. Che il mittente invii un semplice oggetto JSON piatto o un payload profondamente annidato, l'intero body arriva in {{ trigger.output.payload }} esattamente come ricevuto. Questo rende il Webhook Trigger adatto all'integrazione con praticamente qualsiasi servizio di terze parti che supporti webhook in uscita.

Per proteggere il tuo workflow da chiamanti non autorizzati, il Webhook Trigger supporta due modalità di autenticazione: Header Secret (un token segreto condiviso verificato in un header denominato) e HMAC Signature (un hash crittografico del corpo della richiesta verificato con una chiave di firma). Dovresti sempre configurare una di queste in produzione.

Il tuo URL Webhook

L'URL webhook del tuo workflow viene mostrato in cima al pannello di configurazione del Webhook Trigger. Segue questo formato:

https://your-flusso-instance.com/api/webhooks/{workflow-id}

Copia questo URL e incollalo nella configurazione webhook del servizio esterno che vuoi collegare. L'URL è permanente — non cambia anche se rinomini il workflow.

Configurazione

Campo	Obbligatorio	Descrizione
Auth Type	Obbligatorio	Come autenticare le richieste in arrivo. Scegli una tra: None — nessuna autenticazione. Qualsiasi richiesta all'URL attiverà il workflow. Non raccomandato per la produzione. Header Secret — il mittente deve includere un header specifico con un valore segreto che definisci. HMAC Signature — il mittente firma il corpo della richiesta con un segreto condiviso usando HMAC-SHA256; Flusso valida la firma.
Header Name	Condizionale	Mostrato solo quando Auth Type è impostato su Header Secret. Il nome dell'header HTTP che il mittente deve includere (ad esempio, `X-Webhook-Token` o `Authorization`).
Secret	Condizionale	Il valore segreto (per la modalità Header Secret) o la chiave di firma HMAC (per la modalità HMAC Signature). In modalità Header Secret, Flusso rifiuta le richieste in cui il valore dell'header non corrisponde esattamente a questa stringa. In modalità HMAC, Flusso calcola la firma attesa e rifiuta le richieste in cui le firme non corrispondono.

Dati di Output

Il Webhook Trigger espone tre variabili di output ai passaggi downstream:

Variabile	Tipo	Descrizione
`trigger.output.payload`	Object / Array	Il corpo completo della richiesta, analizzato come JSON. Se il mittente invia dati di form, vengono convertiti in un oggetto.
`trigger.output.headers`	Object	Tutti gli header della richiesta HTTP come coppie chiave-valore (i nomi degli header sono in minuscolo).
`trigger.output.method`	String	Il metodo HTTP della richiesta in arrivo (sempre `POST` per i mittenti webhook standard).

// Accedere ai campi all'interno del payload {{ trigger.output.payload.order_id }} {{ trigger.output.payload.customer.email }} // Accedere a un header specifico della richiesta {{ trigger.output.headers.content-type }} // Verificare il metodo HTTP {{ trigger.output.method }}

Esempio di Utilizzo

Ricevere l'invio di un modulo da un sito web esterno

Crea il workflow e aggiungi un Webhook Trigger. Imposta Auth Type su Header Secret, inserisci X-Form-Token come nome dell'header e scegli una lunga stringa casuale come segreto.
Copia l'URL webhook dal pannello di configurazione del trigger.
Configura il tuo form builder o sito web per inviare un POST a quell'URL all'invio, includendo l'header X-Form-Token: your-secret. I campi del modulo arriveranno nel payload.
Nei passaggi successivi del workflow, referenzia i campi inviati come {{ trigger.output.payload.name }} e {{ trigger.output.payload.email }}.

Suggerimenti e Note

Usa sempre l'autenticazione in produzione. Un URL webhook con Auth Type impostato su None eseguirà il tuo workflow per qualsiasi richiesta da chiunque su internet. Usa Header Secret come minimo, o HMAC Signature per i servizi che lo supportano.

La modalità HMAC Signature è più sicura di Header Secret perché anche se qualcuno intercetta una richiesta, non può riprodurla con dati modificati — la firma non corrisponderebbe più. Usa HMAC quando il servizio mittente lo supporta (Stripe, GitHub e Shopify hanno ciascuno nodi trigger dedicati che gestiscono automaticamente la validazione della firma).
Il workflow risponde con HTTP 200 immediatamente alla ricezione della richiesta. L'esecuzione del workflow è asincrona — se hai bisogno di restituire una risposta personalizzata al chiamante, usa il nodo Webhook Response nel tuo workflow.
Limite dimensione payload: Flusso accetta corpi delle richieste fino a 10 MB. Per payload più grandi, considera di passare un URL ai dati anziché i dati stessi.
Testing: Usa uno strumento come webhook.site o gli strumenti per sviluppatori del tuo browser per ispezionare le richieste in uscita dal tuo servizio esterno prima di collegarlo a Flusso.

Nodi Correlati

Webhook Response — invia una risposta sincrona al chiamante del webhook.
Manual Trigger — avvia il workflow su richiesta senza una richiesta esterna.
Stripe Trigger — trigger webhook con validazione integrata della firma Stripe.
GitHub Trigger — trigger webhook con validazione HMAC integrata di GitHub.
Shopify Trigger — trigger webhook con validazione HMAC integrata di Shopify.