Nodo Webhook Trigger - Integrazione Fire&Forget e Fire&Wait in ConvyAI

Overview

Il nodo Webhook Trigger avvia un Agentic Flow quando un sistema esterno invia una richiesta HTTP a un endpoint univoco generato automaticamente dalla piattaforma. Il nodo supporta due modalità di risposta: fire&forget, in cui la piattaforma conferma immediatamente la ricezione e processa il flusso in background, e fire&wait, in cui la chiamata HTTP resta aperta fino al termine del flusso e il chiamante riceve direttamente nella risposta l'output prodotto dal flusso.

Posizionamento

Il nodo Webhook Trigger non ha connessioni in ingresso e deve essere posizionato come primo nodo del flusso. Può coesistere con altri tipi di trigger (Manual Trigger, Scheduled Trigger) nello stesso flusso.

Configurazione

Endpoint

Campo	Descrizione
Metodo HTTP	Il metodo HTTP accettato dall'endpoint (es. POST, GET).
Webhook URL	Generata automaticamente, in sola lettura. Univoca per tenant, flusso e nodo.

Autenticazione

Campo	Descrizione
App Token	Token applicativo del tenant. Le richieste in ingresso devono includere questo token per essere autenticate. Usa il pulsante di copia per copiarlo.
Whitelist IP	Lista opzionale di indirizzi IP, domini o maschere IP autorizzati a richiamare l'endpoint. Lascia vuoto per consentire tutte le sorgenti.

Modalità di risposta

Campo	Descrizione
Response mode	Seleziona come il nodo risponde al sistema chiamante: fire&forget (default) o fire&wait.

Comportamento in esecuzione

Fire&forget

Quando un sistema esterno chiama l'URL webhook, ConvyAI conferma immediatamente la ricezione con HTTP 202 e avvia il flusso in background - il sistema chiamante non attende il completamento del flusso.

Fire&wait

La chiamata HTTP resta aperta per tutta la durata dell'esecuzione del flusso. La risposta viene inviata solo al termine:

• Esecuzione completata - il chiamante riceve HTTP 200 con l'output prodotto dall'ultimo nodo eseguito nel flusso, indipendentemente dalla sua tipologia:

  {
    "execution_id": "<id>",
    "result": { /* output dell'ultimo nodo eseguito */ }
  }

  Non è necessario un nodo Result per ottenere questa risposta.
• Timeout di piattaforma raggiunto - se l'esecuzione supera il timeout configurato a livello di piattaforma, il run viene interrotto forzatamente e il chiamante riceve HTTP 504:

  {
    "execution_id": "<id>",
    "error": "execution_timeout"
  }

• Stop manuale - se il run viene interrotto manualmente mentre il chiamante è in attesa, il chiamante riceve HTTP 409.

In tutti e tre i casi il run è visibile nella pagina Monitoring con il proprio stato finale al termine della chiamata.

Errori comuni a entrambe le modalità

Se la chiamata viene rifiutata perché il metodo HTTP non corrisponde a quello configurato (405), o perché le credenziali non sono valide (401/403), il flusso non viene avviato, indipendentemente dalla modalità di risposta configurata.

Output

La richiesta in ingresso è disponibile ai nodi successivi tramite la notazione standard di accesso all'output di un nodo $('<nome-nodo>').output.<campo>, dove <nome-nodo> è il nome assegnato a questo nodo in Agentic Designer.

Campo	Tipo	Descrizione
request.body	object	Body JSON della richiesta HTTP.
request.query	object	Parametri della query string.
request.headers	object	Header HTTP della richiesta in ingresso.

Esempio - accesso al body della richiesta da un nodo successivo:

$('Webhook Trigger').output.request.body

Concetti chiave

Termine	Definizione
Fire&forget	Modalità di gestione in cui il sistema risponde immediatamente al chiamante senza attendere il completamento del flusso.
Fire&wait	Modalità di gestione in cui la chiamata HTTP resta aperta fino al termine del flusso, e il chiamante riceve direttamente nella risposta l'output prodotto dal flusso.
App Token	Token applicativo del tenant usato per autenticare le chiamate al webhook.
Whitelist IP	Lista opzionale di IP, domini o maschere IP autorizzati a invocare l'endpoint webhook.