Blocco Webhook - Ricevi chiamate HTTP in entrata nel flusso del chatbot

Metti in pausa il flusso del tuo chatbot ChatMaxima in attesa di una chiamata HTTP esterna. Ricevi payload, riprendi il flusso e invia risposte HTTP personalizzate al chiamante.

Panoramica

Il Blocco Webhook permette a un sistema esterno di chiamare il tuo chatbot via HTTP. Può essere usato in due modi: come primo blocco di un flusso (il webhook stesso avvia la conversazione), oppure come blocco a metà flusso che mette in pausa la conversazione e attende una callback esterna per riprenderla. In entrambi i casi, il payload in arrivo viene analizzato e reso disponibile ai blocchi successivi come variabili. Puoi facoltativamente inviare una risposta HTTP personalizzata al chiamante usando il Blocco Risposta Webhook.

Questo è l'inverso del Blocco API. Il Blocco API invia richieste in uscita. Il Blocco Webhook ascolta le richieste in entrata. I casi d'uso tipici includono l'avvio di una nuova conversazione da un evento esterno (l'invio di un modulo, la creazione di un record CRM, un trigger iPaaS come n8n o Zapier), l'attesa di una callback da un gateway di pagamento, la ricezione della conferma di consegna OTP da un provider SMS di terze parti, la notifica al completamento di un job di backend a lunga esecuzione o l'accettazione di aggiornamenti asincroni da un'app esterna.

Blocco Webhook vs Blocco API

Aspetto	Blocco API	Blocco Webhook
Direzione	In uscita (il bot chiama l'API)	In entrata (il sistema esterno chiama il bot)
Trigger	Automatico quando il flusso raggiunge il blocco	Un POST HTTP esterno avvia o riprende il flusso
Posizionamento	Solo a metà flusso	Primo blocco o a metà flusso
Comportamento di attesa	Sincrono, timeout di 30 secondi	Avvia il flusso all'arrivo, o mette in pausa il flusso fino all'arrivo della chiamata
Uso tipico	Cercare dati, inviare aggiornamenti	Avviare conversazioni da eventi esterni, attendere callback asincrone
Gestione della risposta	Analizza il body della risposta in variabili	Il payload in arrivo diventa variabili

Dove trovarlo

Apri il tuo chatbot in Studio
Trascina il blocco Webhook dalla barra laterale sinistra sulla canvas
Posizionalo come primo blocco del tuo flusso (per avviare una conversazione da un evento esterno) o collegalo dopo un blocco precedente qualsiasi (per mettere in pausa e attendere una callback a metà flusso)
Fai doppio clic sul blocco per configurarlo

Per inviare una risposta HTTP personalizzata al chiamante, aggiungi un blocco Risposta Webhook subito dopo il blocco Webhook.

Webhook come primo blocco

Quando il blocco Webhook è il primo blocco del flusso, non c'è ancora una conversazione attiva. Il POST esterno crea la conversazione, analizza il payload in variabili e avvia il flusso dall'inizio. Questo è il pattern da usare quando:

Un nuovo lead viene creato nel tuo CRM e vuoi che il bot lo contatti
Un modulo viene inviato sul tuo sito web e vuoi che il bot dia seguito
Un workflow n8n, Zapier o Make attiva una nuova sessione di chat
Un evento di backend (ordine effettuato, ticket di assistenza aperto) dovrebbe avviare una conversazione del bot

Webhook a metà flusso

Quando il blocco Webhook è posizionato dopo un altro blocco, il flusso si mette in pausa a quel punto fino all'arrivo del POST esterno. Questo è il pattern da usare quando devi passare il testimone a un sistema esterno, attendere la sua risposta asincrona, poi continuare il flusso in base a ciò che ha restituito.

Come funziona

Modalità primo blocco

External system POSTs to webhook URL
                 │
                 ▼
   New conversation is created
                 │
                 ▼
   Payload parsed into variables
                 │
                 ▼
   Flow starts from the next block
                 │
                 ▼
   Webhook Response sent (optional)

Modalità a metà flusso

Bot flow runs ──▶ Reaches Webhook Block ──▶ Flow pauses
                                                  │
                             External system POSTs to webhook URL
                                                  │
                                                  ▼
                            Payload parsed into variables
                                                  │
                                                  ▼
                     Webhook Response sent (optional)
                                                  │
                                                  ▼
                     Flow continues to next block

In modalità a metà flusso, il bot memorizza la posizione corrente del blocco quando si mette in pausa. Quando il POST esterno arriva all'URL del webhook, il sistema lo abbina alla conversazione in pausa, riprende da quel blocco e continua verso valle.

Configurazione

Passaggio 1: Posiziona il blocco Webhook nel flusso

Trascina il blocco sulla canvas nel punto in cui il flusso deve avviarsi o attendere un evento esterno. Per esempio:

Come primo blocco, per permettere a un CRM, un modulo o uno strumento iPaaS di avviare una nuova conversazione di chat
Dopo l'acquisizione dei dettagli di pagamento, per attendere la conferma del gateway di pagamento
Dopo aver attivato un job di backend tramite un blocco API, per attendere la notifica di job completato

Passaggio 2: Copia l'URL del webhook

Ogni blocco Webhook espone un URL univoco mostrato nella configurazione del blocco. Il formato è:

https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/

Passa questo URL al sistema esterno come destinazione per la sua richiesta POST. Per gli strumenti iPaaS (n8n, Zapier, Make) lo incolli nel passaggio HTTP. Per i CRM e i form builder, configuralo come webhook in uscita nella loro dashboard. Per i gateway di pagamento e i backend asincroni, impostalo come URL di callback quando avvii il lavoro.

Passaggio 3: Autentica il chiamante

L'URL del webhook accetta un token Bearer nell'header Authorization. Usa il token mostrato nella configurazione del blocco così che il webhook accetti solo chiamate da sistemi di cui ti fidi.

curl -X POST https://chatmaxima.com/webhooks/chatbot/<bot_token>/<block_id>/ \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer <your_token>' \
  --data '{
    "type": "Conversation",
    "channel": "",
    "account_alias": "",
    "reference_id": "",
    "data": {
      "name": ""
    }
  }'

Struttura del payload

Campo	Scopo
`type`	Tipo di evento, tipicamente `Conversation` per avviare o riprendere una chat
`channel`	Canale che la conversazione dovrebbe usare (es. `whatsapp`, `website`). Lascia vuoto per usare il predefinito
`account_alias`	Alias del team quando il bot è condiviso tra più account
`reference_id`	Identificatore esterno che puoi usare per collegare la conversazione a un record nel tuo sistema
`data`	Oggetto contenente qualsiasi campo che vuoi passare come variabili (es. `name`, `email`, `phone`, campi personalizzati)

Passaggio 4: Referenzia i campi del payload in arrivo

Quando il POST arriva, l'oggetto data viene analizzato e ogni campo diventa una variabile disponibile a tutti i blocchi successivi.

Per un payload come:

{
  "type": "Conversation",
  "channel": "whatsapp",
  "reference_id": "ORDER-9981",
  "data": {
    "name": "Priya",
    "phone": "+919000000000",
    "order_id": "ORDER-9981",
    "customer": {
      "email": "priya@example.com"
    }
  }
}

Puoi referenziare:

{name} per Priya
{phone} per +919000000000
{order_id} per ORDER-9981
{customer.email} per i campi annidati
{reference_id} per i metadati di primo livello

Passaggio 5: Invia e salva

Clicca su Invia nel modale del blocco, poi salva il flusso usando Salva modifiche nella barra superiore.

Blocco Risposta Webhook

Abbina il blocco Webhook a un Blocco Risposta Webhook quando il chiamante si aspetta una risposta HTTP specifica. Senza il blocco di risposta, il bot restituisce un 200 OK predefinito con {"status":"success"}.

Il Blocco Risposta Webhook ti permette di personalizzare il codice di stato (es. 201, 400, 500), il content type (application/json, application/xml, text/plain, text/html) e il body della risposta inviata al chiamante. Puoi inserire variabili di flusso con la sintassi {variable_name}.

Pattern comuni:

Restituire 201 Created con il nuovo {conversation_id} per gli strumenti iPaaS
Restituire 400 con un campo di errore quando il payload non è valido
Restituire text/plain OK per le callback di consegna SMS
Restituire XML per le integrazioni SOAP legacy

Consulta la documentazione completa del Blocco Risposta Webhook per le opzioni di configurazione, gli esempi e la risoluzione dei problemi.

Best practice

Valida sempre i payload in arrivo. Usa un blocco Condizione dopo il blocco Webhook per verificare campi come status == "success" prima di procedere
Usa il blocco Risposta Webhook quando il chiamante (gateway di pagamento, provider SMS, ecc.) si aspetta un formato di conferma specifico. Senza di esso, il chiamante ottiene un generico 200 OK
Imposta un timeout significativo altrove. Il blocco Webhook in sé non va in timeout, quindi combinalo con il Timeout di inattività per evitare flussi che restano in pausa indefinitamente
Proteggi l'URL del webhook. Il token nell'URL è univoco per conversazione. Non esporre l'URL pubblicamente né registrarlo in sistemi leggibili dall'utente
Gestisci il caso di fallimento. Dirama il flusso in base al payload in arrivo. Se l'evento esterno indica un fallimento, invia un messaggio di recupero o instrada a un agente

Casi d'uso comuni

Un lead CRM crea una conversazione (primo blocco)

Un nuovo lead viene aggiunto nel tuo CRM, e il bot apre una conversazione WhatsApp per qualificarlo.

Blocco Webhook (primo blocco): Il CRM invia in POST il payload del lead con phone, name, source
Blocco Messaggio: Hi {name}, thanks for your interest!
Blocco Domanda: Poni domande di qualificazione
Blocco API: Invia i dati qualificati di nuovo al CRM

Trigger n8n o Zapier (primo blocco)

Uno strumento di automazione attiva un webhook quando si verifica un evento specifico (nuovo ordine Shopify, invio Typeform, ecc.), e il bot dà seguito con il cliente.

Blocco Webhook (primo blocco): n8n invia in POST {"phone":"...", "order_id":"..."}
Blocco Messaggio: Your order {order_id} has shipped!

Callback del gateway di pagamento

L'utente avvia un pagamento, il bot lo indirizza a una pagina di pagamento, poi attende che il gateway invii in POST il risultato.

Blocco API: Crea una sessione di pagamento, memorizza payment_url
Blocco Messaggio: Invia payment_url all'utente
Blocco Webhook: Metti in pausa il flusso, passa l'URL del webhook al gateway come callback
Blocco Condizione: Si dirama su {status} == "success"
Blocco Risposta Webhook: Restituisci {"received":true} al gateway

Notifica di job asincrono

Il bot attiva un job di generazione report a lunga esecuzione, attende il completamento, poi invia il link del report all'utente.

Blocco API: Invia il job, memorizza job_id, includi l'URL del webhook come callback
Blocco Messaggio: "Sto generando il tuo report, potrebbe volerci un minuto..."
Blocco Webhook: Attendi la callback di job completato
Blocco Messaggio: Your report is ready: {report_url}

Stato di consegna OTP di terze parti

Il bot invia un OTP tramite un provider SMS esterno che usa i webhook per confermare la consegna.

Blocco API: Attiva l'invio dell'OTP, passa l'URL del webhook
Blocco Webhook: Attendi lo stato di consegna
Blocco Condizione: Si dirama su {delivery_status}
Blocco Messaggio: Chiedi il codice OTP o scusati per la mancata consegna

Invio di un modulo esterno

Un'app web separata raccoglie informazioni aggiuntive e le invia in POST al bot quando l'utente termina.

Blocco Messaggio: Invia l'URL del modulo all'utente
Blocco Webhook: Attendi l'invio del modulo
Blocco Messaggio: Thanks, we received your {form_field}

Risoluzione dei problemi

Il flusso è bloccato sul blocco Webhook (a metà flusso)

Conferma che il sistema esterno abbia effettivamente inviato in POST all'URL del webhook. Controlla i suoi log di consegna
Verifica che l'URL sia raggiungibile dal sistema esterno (non bloccato da firewall o allowlist di IP)
Assicurati che l'URL includa il percorso completo e il token finale
Combina con il Timeout di inattività per chiudere automaticamente le conversazioni che non ricevono mai la callback

Il webhook come primo blocco non avvia una conversazione

Conferma che il blocco Webhook sia il primissimo blocco del flusso (nessun altro blocco si collega ad esso)
Verifica che il payload includa un identificatore del destinatario (telefono, email o ID visitatore) che il bot possa usare per creare la conversazione
Controlla che il bot sia pubblicato e che il canale (WhatsApp, widget del sito web, ecc.) sia connesso
Ispeziona lo stato della risposta restituito al chiamante. Un 4xx indica che il payload è stato rifiutato

I campi del payload in arrivo sono vuoti nei blocchi successivi

Conferma che il Content-Type del POST in arrivo sia application/json o un tipo di form supportato
Controlla i nomi esatti dei campi nel payload. I nomi delle variabili sono sensibili alle maiuscole
Per i campi annidati, usa la notazione con punto: {customer.email}, non {customer_email}
Ispeziona il payload grezzo in arrivo nel log della conversazione per vedere cosa è stato effettivamente ricevuto

Il chiamante ottiene un generico `200 OK` invece della mia risposta personalizzata

Assicurati di aver aggiunto un blocco Risposta Webhook dopo il blocco Webhook
Verifica che il blocco di risposta sia raggiungibile nel grafo del flusso. Un blocco Condizione potrebbe aggirarlo nell'instradamento
Ricontrolla che il pulsante Invia sia stato cliccato e che il flusso sia stato salvato

Il sistema esterno rifiuta la risposta del webhook

Conferma che il Content-Type corrisponda a ciò che il chiamante si aspetta (per esempio, application/json vs text/plain)
Valida che il body della risposta sia ben formato. Un oggetto JSON non chiuso causerà nuovi tentativi da parte dei chiamanti rigorosi
Controlla il codice di stato HTTP. Alcuni chiamanti accettano solo 200, non 201 o 202

Arrivano più POST per la stessa conversazione

Alcuni sistemi esterni ritentano i webhook se ritengono che la prima consegna sia fallita. L'URL del webhook è idempotente per conversazione, quindi solo il primo POST valido riprende il flusso. I POST successivi ricevono la risposta configurata senza far avanzare di nuovo il flusso.

Prossimi passi

Blocco Risposta Webhook - Invia risposte HTTP personalizzate al chiamante
Blocco API - Chiama API esterne dal flusso
Timeout di inattività - Chiudi automaticamente le conversazioni che restano in pausa troppo a lungo
Blocco Fine conversazione - Termina manualmente le conversazioni con un pulsante di riavvio
Panoramica di Studio - Esplora tutti i tipi di blocco e le funzionalità del flow builder