> For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.userbot.ai/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.userbot.ai/_mcp/server. # Webhook Il trigger **Webhook** dà al workflow un indirizzo suo. Quando un altro sistema (il gestionale, un e-commerce, uno script interno) manda una richiesta a quell'indirizzo, il flusso parte con i dati che la richiesta contiene. Serve quando l'evento che deve avviare il lavoro nasce in un sistema che sapete già programmare. Se nasce in un'app che avete collegato a Userbot, come Gmail o Google Calendar, è più semplice il trigger **Integrazione**. → [Avvio da eventi delle app](/trigger-integrazione) ## Configurarlo #### Scegli Webhook nel trigger Clicca il blocco **Trigger** e, in cima al pannello, scegli la scheda **Webhook**. Gli indirizzi si generano da soli e non si scrivono a mano. ![Il pannello del blocco Trigger con le tre schede in cima, Manuale, Integrazione e Webhook](/_fern-img/ee4c031e943505dba257ce3dd766e521d309f72a3bef46a57c804241041e71d1.webp) #### Copia l'indirizzo giusto In **Parametri** scegli **Produzione** o **Test** e premi **Copia** accanto a **URL webhook**. La differenza fra i due è spiegata qui sotto. Copia sempre l'indirizzo dal tuo workflow: quello nell'immagine viene da un ambiente di prova. ![La scheda Webhook del trigger: sotto la spiegazione, le schede Parametri, Sicurezza e Audit logs; in Parametri i pulsanti Produzione e Test, il campo URL webhook con Copia evidenziato accanto e, sotto, Rigenera URL](/_fern-img/c56a6ffeb909eaf9c57fc82a904f2c47beb52044e618f13f34c039de28ddfdb7.webp) #### Limita chi può chiamarlo Apri **Sicurezza** e aggiungi le origini o gli indirizzi IP ammessi. Senza restrizioni chiunque abbia l'indirizzo può far partire il flusso. ![La scheda Sicurezza del webhook: una riga che spiega perché conviene limitarlo e i due campi Origin Whitelist e IP Whitelist, affiancati](/_fern-img/60b0d6a991fabe4c4c05ff5ed99a667e72d1494ca97e16cdc394687832abab29.webp) #### Pubblica L'indirizzo di produzione risponde solo quando il workflow è attivo e ha una versione pubblicata con questo trigger. → [Pubblicare e monitorare](/pubblicare-workflow) ## Produzione e Test | | Produzione | Test | | --------------- | ---------------------------------------- | -------------------------------- | | Cosa esegue | La versione pubblicata | La bozza così come l'hai salvata | | Quando risponde | Solo con il workflow attivo e pubblicato | Sempre | | Dove lo usi | Nel sistema che chiama davvero | Mentre costruisci e provi | Gli avvii arrivati sull'indirizzo **Test** non compaiono in **Analytics**. Nella cronologia del workflow i due casi si distinguono dall'origine, **Webhook · Prod** oppure **Webhook · Test**. ### Provare con Ascolta #### Scegli Test In **Parametri** premi **Test**: il campo **URL webhook** mostra l'indirizzo di prova, e accanto a **Rigenera URL** compare **Ascolta**. #### Premi Ascolta Il pulsante diventa **In ascolto…** e sotto compare **Payload**, in attesa della prima chiamata. ![La scheda Parametri con Test scelto: l'indirizzo di prova, il pulsante In ascolto…, la nota che ogni chiamata avvia un'esecuzione sulla bozza e il Payload ancora in attesa](/_fern-img/ee825e7215c364a46a7ccd2ac2e4dc6b66aee5bb3b3d6bedefce0630f74065be.webp) #### Manda una richiesta all'indirizzo di prova Dal sistema che chiamerà il workflow, oppure da uno strumento per provare le API. Sotto **Payload** compaiono l'indirizzo chiamato e i dati ricevuti, campo per campo. Ogni chiamata all'indirizzo di prova avvia anche un'esecuzione sulla bozza, quindi vedi subito cosa fa il flusso con quei dati. ## Cosa deve mandare chi chiama Una richiesta `POST` con un corpo JSON. Il workflow legge solo l'oggetto `data`: tutto quello che sta lì dentro diventa l'input del flusso, il resto viene ignorato. ```json { "data": { "ordine": "A-1042", "cliente": "mario.rossi@esempio.it", "totale": 129.5 } } ``` Nel flusso questi valori si richiamano con `$input.data`, per esempio `{{$input.data.ordine}}`. Insieme ai dati arriva anche `$input.webhook`, con l'indirizzo chiamato e l'ambiente (`production` o `test`). → [La sintassi dei riferimenti](/riferimenti-dati) La risposta arriva subito, senza aspettare che il flusso finisca: | Codice | Cosa significa | | ------ | -------------------------------------------------------------------------------------------- | | `202` | Richiesta accettata, l'esecuzione è partita. Nella risposta c'è il suo identificativo | | `402` | L'avvio è stato bloccato da un limite: esecuzioni del mese esaurite o un limite del workflow | | `403` | L'origine o l'indirizzo IP di chi chiama non è fra quelli ammessi | | `404` | Indirizzo sconosciuto, oppure in produzione il workflow non è attivo o non è pubblicato | | `429` | Più di 60 richieste in un minuto sullo stesso indirizzo | Se arrivano più richieste mentre un'esecuzione è in corso, le altre aspettano il loro turno. → [Come gira un'esecuzione](/esecuzione-workflow) ## Sicurezza L'indirizzo è una credenziale: chi lo conosce può far partire il flusso, e ogni avvio consuma esecuzioni e credito. Le due liste della scheda **Sicurezza** riducono chi può usarlo. * **Origin Whitelist** accetta solo le richieste che dichiarano di arrivare da uno dei domini elencati, per esempio `https://shop.azienda.it`. Serve quando a chiamare è un sito, dal browser di chi lo visita. * **IP Whitelist** accetta solo le richieste che arrivano dagli indirizzi IP o dagli intervalli elencati. Serve quando a chiamare è un vostro server. > **Warning** > > Un server che chiama il webhook di solito non dichiara un'origine. Se compili > **Origin Whitelist** e la chiamata parte da un server, viene rifiutata con > `403`. Per le chiamate da server usa **IP Whitelist**. Le liste valgono per entrambi gli indirizzi e si applicano appena le salvi, senza ripubblicare. ### Rigenera URL Se pensi che un indirizzo sia circolato dove non doveva, **Rigenera URL** ne crea uno nuovo per l'ambiente selezionato. Il vecchio smette di funzionare subito, anche senza ripubblicare: prima di confermare, preparati ad aggiornare il sistema che lo chiama. Ogni rigenerazione resta nella scheda **Audit logs**, con data, persona, ambiente e nuovo indirizzo, e compare anche nel [Registro di audit](/audit) dell'area di lavoro. ## Errori frequenti #### La chiamata risponde 202 ma nel flusso i dati sono vuoti I dati non sono dentro `data`. Un corpo come `{"ordine": "A-1042"}` viene accettato, ma al flusso arriva un oggetto vuoto. Sposta i campi sotto `"data"`. #### In test funziona, in produzione risponde 404 Il workflow non è attivo, oppure la versione pubblicata non ha ancora il trigger Webhook. Pubblica la bozza: la pubblicazione attiva anche il workflow. #### Risponde 403 Chi chiama non rientra nelle liste di **Sicurezza**. Se hai compilato **Origin Whitelist** e chiama un server, è quasi sempre quella la causa.