# Avviare un'automazione via webhook

> Con un webhook un altro software, come Zapier, Make, il tuo gestionale o il modulo del tuo sito, fa partire un'automazione e le passa i suoi dati, che diventano variabili.

Pagina: https://supportfast.ai/it/guida/sviluppatori/webhook-in-ingresso/ · Sezione: Sviluppatori · Aggiornata il 30 ottobre 2026

## A cosa serve

Un webhook è un indirizzo web a cui un altro software manda dei dati quando succede qualcosa. Ogni automazione con il trigger Webhook ha il suo indirizzo: quando ci arriva una richiesta, l'automazione parte.

- Il modulo «Richiedi un preventivo» del tuo sito manda nome, email e telefono: l'automazione salva il contatto e lo richiama.
- L'e-commerce manda un ordine: l'automazione scrive al cliente su WhatsApp.
- Zapier e Make collegano centinaia di app: qualunque loro evento può far partire un'automazione.

**Il tuo software** — Manda una richiesta POST con i dati in JSON. → **L'indirizzo dell'automazione** — Accetta la richiesta e risponde. → **L'automazione** — Parte e usa i dati come variabili `{{webhook.*}}`.

> **Prima di iniziare**
>
> - La funzione «API e webhook» del piano.
> - Un servizio esterno che sa mandare una richiesta HTTP POST con corpo JSON.

## Ottenere l'indirizzo

1. **Scegli la fonte Webhook**
   Nel Playground dell'automazione premi la scheda del trigger, il nodo di partenza. In Fonte di partenza scegli Webhook (API). Puoi farlo anche mentre crei l'automazione, nella finestra «Nuova Automazione», al passo Trigger.

2. **Genera l'indirizzo**
   Premi Genera indirizzo. Compare l'indirizzo completo, unico per questa automazione, che finisce con `/incoming/` e un codice. Sotto leggi le tre caratteristiche: Post, Application/json, No Auth.

3. **Copialo nel servizio esterno**
   Premi Copia e incolla l'indirizzo dove il servizio esterno chiede l'URL del webhook.

## Fare la prova

La prova è obbligatoria: senza, gli eventi del webhook non avviano l'automazione e l'automazione non si pubblica. Serve anche a far conoscere alla console i campi che arriveranno.

1. **Metti in ascolto**
   In Test Webhook premi Metti in ascolto. Lo stato diventa «In ascolto...».

2. **Manda la richiesta di prova**
   Dal servizio esterno manda un POST all'indirizzo con `/test` aggiunto subito dopo il codice. Se mandi anche dei parametri, `/test` va prima del «?»: per esempio `INDIRIZZO-DEL-WEBHOOK/test?origine=sito`.

3. **Controlla cosa è arrivato**
   Compare «Test ricevuto», con Dati ricevuti e Headers ricevuti. Da adesso i campi sono nel pannello delle variabili, scheda Input, fascia «Dati ricevuti dal webhook».

4. **Costruisci, salva e pubblica**
   Usa le variabili nei nodi, poi premi Salva modifiche e Pubblica.

L'ascolto si spegne quando arriva la prova, quando premi Annulla ascolto, quando lasci il Playground o, se fai la prova mentre crei l'automazione, quando chiudi la finestra «Nuova Automazione». Per rifare la prova premi Rimetti in ascolto.

> **Attenzione**
>
> **Dopo la prova togli `/test`.** In produzione l'indirizzo si usa così com'è. Se in Zapier, in Make o nel tuo software resta l'indirizzo con `/test`, le richieste vere ricevono `404` e l'automazione non parte.

![Pannello del trigger Webhook dopo la prova: indirizzo generato con Copia e Rigenera, pastiglie Post, Application/json e No Auth, e la sezione Test Webhook con Test ricevuto e i Dati ricevuti.](https://supportfast.ai/_astro/05-trigger-webhook-prova.CX3XbNcC.webp)

_Dopo la prova il pannello mostra i dati e gli header ricevuti, che diventano variabili {{webhook.*}}._

## Autenticazione e header

L'indirizzo accetta richieste POST con un corpo JSON. Manda sempre l'intestazione `Content-Type: application/json`: senza, o con un altro tipo, il corpo non viene letto. La richiesta è accettata lo stesso, con `202`, ma l'automazione parte senza i dati del corpo; arrivano solo i parametri dell'indirizzo e gli header. Una prova mandata così registra una struttura vuota.

Il codice nell'indirizzo fa da chiave: custodiscilo come una password, dallo solo ai servizi che devono usarlo, non metterlo nel codice di una pagina web e, se serve, [rigeneralo](https://supportfast.ai/it/guida/sviluppatori/webhook-in-ingresso.md#rigenerare).

Gli header personalizzati che mandi diventano variabili col nome in minuscolo: un header `Negozio` si legge con `{{webhook.headers.negozio}}`. Gli header standard, come host, content-type e user-agent, vengono tolti.

## Il formato dei dati

Il corpo è un oggetto JSON, al massimo 1 MB: oltre, la richiesta è rifiutata con `413` e l'automazione non parte. Ogni campo del corpo, ogni parametro dell'indirizzo (quelli dopo il «?») e ogni header personalizzato diventa una variabile `{{webhook.*}}`: i campi annidati si leggono col punto, gli elementi delle liste con la posizione da 0. La tabella degli [Esempi](https://supportfast.ai/it/guida/sviluppatori/webhook-in-ingresso.md#esempi) mostra ogni caso.

Usa nomi di campo semplici, con lettere, cifre e «_». Nella prova manda la stessa struttura che userai davvero: il pannello delle variabili propone i campi della prova, e un campo che poi non arriva resta vuoto. Se la struttura cambia, rifai la prova con Rimetti in ascolto.

## Esempi

Al posto di `INDIRIZZO-DEL-WEBHOOK` incolla l'indirizzo copiato dalla console.

**curl · una richiesta con un parametro e un header**

```
curl -X POST "INDIRIZZO-DEL-WEBHOOK?origine=sito" \
  -H "Content-Type: application/json" \
  -H "Negozio: officina-rossi" \
  -d '{"nome":"Mario","cognome":"Rossi","email":"mario.rossi@esempio.it","telefono":"+39 02 1234 5678","ordine":{"numero":"A-1029","totale":149.9},"righe":[{"sku":"FILTRO-OLIO","quantita":1}]}'
```

| Dato mandato | Variabile | Valore |
| --- | --- | --- |
| `nome` | `{{webhook.nome}}` | Mario |
| `ordine.totale` | `{{webhook.ordine.totale}}` | 149.9 |
| `righe`, primo elemento, `sku` | `{{webhook.righe[0].sku}}` | FILTRO-OLIO |
| parametro `origine` | `{{webhook.origine}}` | sito |
| header `Negozio` | `{{webhook.headers.negozio}}` | officina-rossi |

**Con Zapier o Make.** Nello scenario aggiungi il passo che manda una richiesta HTTP: in [Zapier](https://zapier.com) l'azione POST dell'app Webhooks by Zapier, in [Make](https://www.make.com) il modulo HTTP. Imposta il metodo POST, l'indirizzo copiato e i dati in formato JSON.

## La risposta

Se la richiesta è accettata e il flusso non ha il nodo Risposta Webhook, l'indirizzo risponde subito `202` e l'esecuzione parte:

**JSON · la risposta predefinita**

```
{"success": true, "message": "Webhook received"}
```

Per decidere tu cosa riceve chi chiama, aggiungi al flusso il nodo **Risposta Webhook**. Compare nel menu solo con il trigger Webhook e ha tre campi:

- **Stato della risposta (Menu)**: Il codice HTTP da restituire: 200, 201, 202, 204, 400, 401, 403, 404 o 500.

  (Predefinito: 200 OK)

- **Headers (Chiave e valore, con variabili)**: Gli header da aggiungere alla risposta, con Aggiungi header.

- **Corpo della risposta (JSON) (JSON con variabili)**: Il corpo da restituire, per esempio `{"ok": true, "lead": "{{CRM.id}}"}`. Un valore scritto solo come variabile, come `"{{CRM.id}}"`, mantiene il suo tipo.

Con questo nodo nel flusso la risposta non è più immediata: chi chiama la aspetta per un massimo di **30 secondi**. Se l'automazione non arriva al nodo in tempo, riceve la risposta predefinita, `202`, e l'automazione prosegue comunque. Per questo il nodo va messo presto nel flusso, prima di Attendi, Effettua Chiamata e chiamate API lente. Se il flusso ha più nodi Risposta Webhook, vale il primo.

| Richiesta | Risposta |
| --- | --- |
| POST all'indirizzo, con JSON valido | `202` subito con la risposta predefinita; con il nodo Risposta Webhook, la sua risposta entro 30 secondi. |
| POST senza `Content-Type: application/json` | `202`, ma il corpo non viene letto: vedi [Autenticazione e header](https://supportfast.ai/it/guida/sviluppatori/webhook-in-ingresso.md#autenticazione-e-header). |
| POST all'indirizzo con `/test`, mentre la prova è in ascolto | `200` con `{"test": true, "data": …}`, e l'ascolto si spegne. |
| POST all'indirizzo con `/test`, senza ascolto | `404`. Premi Metti in ascolto e rimanda la richiesta. |
| GET all'indirizzo | `200` con `{"success": true}` se l'automazione è pronta a ricevere, altrimenti `404`. |
| Corpo che non è JSON valido | `400`, anche se l'indirizzo non è pronto: il corpo si controlla per primo. Rivedi virgolette, virgole e parentesi. |
| Corpo oltre 1 MB | `413`. Manda meno dati, per esempio solo i campi che l'automazione usa. |
| Più di 60 richieste in un minuto sullo stesso indirizzo | `429` con `{"error": "Too many requests", "retryAfter": 60}` e l'header `Retry-After: 60`. Riprova dopo i secondi indicati. |
| Indirizzo non pronto o non valido | `404` con `{"error": "Webhook not found"}`. L'automazione non è Attiva o è stata eliminata, l'indirizzo è stato rigenerato, il trigger non è più Webhook, la prova non è mai stata fatta, oppure il piano non comprende «API e webhook». Controlla che l'automazione sia Attiva e usa l'indirizzo attuale. |

## Limiti

- Al massimo 60 richieste al minuto sullo stesso indirizzo, prove comprese. Il conto parte dalla prima richiesta e si azzera dopo 60 secondi. Oltre, la risposta è `429` con l'header `Retry-After`, e la richiesta non avvia l'automazione: rimandala dopo i secondi indicati. Ogni risposta porta anche gli header `X-RateLimit-Limit` e `X-RateLimit-Remaining`, con il limite e le richieste che restano.
- Il corpo può pesare al massimo 1 MB: oltre, la risposta è `413`.

Distribuisci le richieste nel tempo.

## Come verificare

1. **Manda una richiesta vera**
   Se la risposta non è quella attesa, cercala nella tabella qui sopra.

2. **Apri l'esecuzione**
   In Automazioni › Dashboard, nel Log delle esecuzioni, apri la riga nuova. Nella scheda «Evento iniziale», i Dati dell'evento mostrano il corpo ricevuto.

## Rigenerare l'indirizzo

Premi Rigenera accanto all'indirizzo, poi Conferma e Rigenera. Il vecchio indirizzo smette subito di funzionare: aggiorna quello nuovo in tutti i servizi esterni che lo usano. I dati della prova restano: non serve rifarla.

Un'automazione duplicata ha un indirizzo tutto suo, da generare e provare.

## Leggi anche

- [Eventi di partenza (trigger)](https://supportfast.ai/it/guida/automazioni/trigger.md): Il webhook e gli eventi interni a confronto.

- [Chiamare un'API esterna](https://supportfast.ai/it/guida/sviluppatori/chiamate-api.md): La strada opposta: l'automazione che chiama il tuo software.

- [Esempi pronti](https://supportfast.ai/it/guida/automazioni/esempi.md): Un lead da un modulo esterno, salvato nel CRM.