Blocco Risposta Webhook - Invia risposte HTTP personalizzate ai chiamanti

Panoramica

Il Blocco Risposta Webhook ti permette di inviare una risposta HTTP personalizzata a qualunque sistema abbia chiamato il tuo Blocco Webhook. Senza questo blocco, ChatMaxima risponde con un generico 200 OK e un body di {"status":"success"}. Va bene per la maggior parte delle callback, ma alcune integrazioni si aspettano una struttura, un codice di stato o un content type specifici prima di considerare la consegna riuscita.

Usa il Blocco Risposta Webhook quando il chiamante è rigoroso riguardo alla risposta: gateway di pagamento che ritentano a meno che non vedano un particolare campo JSON, sistemi SOAP legacy che si aspettano XML, strumenti iPaaS che analizzano la risposta nei passaggi successivi o form builder che mostrano la risposta all'utente.

Blocco Webhook vs Blocco Risposta Webhook

Aspetto	Blocco Webhook	Blocco Risposta Webhook
Direzione	Riceve la chiamata HTTP in entrata	Invia la risposta HTTP al chiamante
Posizionamento	Primo blocco o a metà flusso	Ovunque a valle di un blocco Webhook
Obbligatorio	Sì (per accettare chiamate esterne)	Facoltativo (se omesso, viene inviato un 200 OK predefinito)
Scopo	Attivare o riprendere il flusso	Definire la struttura della risposta HTTP al chiamante

Dove trovarlo

1. Apri il tuo chatbot in Studio
2. Trascina il blocco Risposta Webhook dalla barra laterale sinistra sulla canvas
3. Collegalo a valle del blocco Webhook che ha ricevuto la richiesta
4. Fai doppio clic sul blocco per configurarlo

Il blocco Risposta Webhook non deve essere il blocco immediatamente successivo. Puoi posizionare blocchi Condizione, API, Imposta variabile e Messaggio tra il blocco Webhook e il blocco Risposta Webhook. Quando il blocco di risposta viene raggiunto durante l'esecuzione del flusso, la sua configurazione diventa la risposta HTTP per il chiamante originale.

Configurazione

Passaggio 1: Imposta il codice di stato HTTP

Codice di stato	Usa quando
200	Predefinito. Indica successo alla maggior parte dei chiamanti
201	Utile quando il webhook ha creato una risorsa (es. una nuova conversazione)
202	Accettato per l'elaborazione asincrona (il bot agirà in seguito)
400	Rifiuta i payload malformati
401	Rifiuta i chiamanti non autorizzati
500	Indica un fallimento lato bot per la logica di nuovo tentativo

Passaggio 2: Imposta il Content-Type

Content-Type	Usa quando
application/json	La maggior parte delle integrazioni moderne (predefinito)
application/xml	Chiamanti in stile SOAP legacy
text/plain	Callback in stile health-check
text/html	Conferme di invio modulo mostrate a un utente

Passaggio 3: Scrivi il body della risposta

Il body è un campo di testo libero. Scrivi il payload esatto che vuoi restituire al chiamante. Le variabili catturate in precedenza nel flusso possono essere inserite con la sintassi {variable_name} (parentesi graffe singole).

Per JSON:

{
  "received": true,
  "conversation_id": "{conversation_id}",
  "lead_id": "{reference_id}",
  "acknowledged_at": "{current_time}"
}

Per XML:

<response>
  <status>success</status>
  <conversation_id>{conversation_id}</conversation_id>
</response>

Per testo semplice:

OK

Passaggio 4: Invia e salva

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

Come funziona

External system POSTs to webhook URL
                 │
                 ▼
       Webhook Block fires
                 │
                 ▼
   (Optional) intermediate blocks:
   - Condition to validate payload
   - API Block to enrich data
   - Set Variable to compute fields
                 │
                 ▼
    Webhook Response Block reached
                 │
                 ▼
    Custom HTTP response returned
    to the original caller
                 │
                 ▼
    Flow continues to downstream blocks
    (messages, further logic, etc.)

La risposta HTTP viene inviata in modo sincrono: il chiamante esterno resta connesso finché non viene raggiunto il blocco di risposta. Per questo motivo, mantieni veloce il percorso tra il blocco Webhook e il blocco Risposta Webhook. Evita chiamate API a lunga esecuzione o logica che richiede tempo prima del blocco di risposta, altrimenti il chiamante potrebbe andare in timeout.

Casi d'uso comuni

Conferma con l'ID conversazione

Uno strumento iPaaS (n8n, Zapier, Make) vuole registrare l'ID della conversazione nel proprio sistema dopo aver attivato il webhook.

• Codice di stato: 201
• Content-Type: application/json
• Body:

{
  "created": true,
  "conversation_id": "{conversation_id}",
  "reference_id": "{reference_id}"
}

Restituisci il risultato della validazione

Un form builder invia in POST l'input dell'utente. Il bot lo valida e restituisce un esito pass/fail così che il modulo possa mostrare il messaggio giusto.

• Codice di stato: 200
• Content-Type: application/json
• Body:

{
  "valid": true,
  "message": "Your request has been received"
}

Rifiuta i payload non validi

Combina un blocco Condizione (che controlla i campi obbligatori) con un blocco Risposta Webhook sul ramo di fallimento che restituisce 400.

• Codice di stato: 400
• Content-Type: application/json
• Body:

{
  "error": "missing_required_field",
  "field": "{missing_field}"
}

Conferma del gateway di pagamento

Un gateway di pagamento invia in POST un webhook settle. Il bot deve restituire una specifica struttura JSON o il gateway continuerà a ritentare.

• Codice di stato: 200
• Content-Type: application/json
• Body:

{
  "status": "acknowledged",
  "transaction_id": "{transaction_id}"
}

Ricevuta di consegna SMS

Un provider SMS legacy si aspetta una risposta in testo semplice OK.

• Codice di stato: 200
• Content-Type: text/plain
• Body: OK

Best practice

• Mantieni breve il percorso. Posiziona blocchi tra il Webhook e la Risposta Webhook solo se vengono eseguiti rapidamente. Le chiamate API lunghe dovrebbero andare dopo il blocco di risposta così che il chiamante non vada in timeout
• Rispondi sempre rapidamente per i chiamanti che ritentano. I gateway di pagamento e i provider SMS spesso ritentano entro pochi secondi. Raggiungere il blocco di risposta entro un secondo o due evita notifiche duplicate
• Corrispondi esattamente alla struttura attesa dal chiamante. I chiamanti rigorosi rifiutano le risposte anche quando il codice di stato è corretto. Leggi la documentazione dell'integrazione e testa con le loro richieste di esempio
• Usa i blocchi Condizione per diramare la risposta. Posiziona un blocco Risposta Webhook sul ramo di successo e uno diverso (con 400 o 401) sul ramo di fallimento
• Includi l'ID conversazione o di riferimento. Questo facilita la correlazione dei log del chiamante con la conversazione in ChatMaxima
• Non inserire dati sensibili nella risposta. La risposta è visibile al chiamante. Restituisci solo ciò che gli serve per confermare la ricezione

Risoluzione dei problemi

Il chiamante riceve il 200 OK predefinito invece della mia risposta personalizzata

1. Conferma che un blocco Risposta Webhook sia presente e raggiungibile dal blocco Webhook
2. Controlla il grafo del flusso: se una Condizione aggira il blocco di risposta nell'instradamento, viene usato il predefinito
3. Assicurati che il blocco sia stato salvato. Clicca su Invia nel modale, poi su Salva modifiche nella barra superiore

Il chiamante ritenta ripetutamente

1. Assicurati che il codice di stato corrisponda a ciò che il chiamante considera successo. Alcuni provider accettano solo 200, non 201 o 202
2. Verifica che il body della risposta corrisponda alla struttura attesa dal chiamante. Ispeziona la sua documentazione o i suoi log
3. Controlla la presenza di blocchi a monte tra il Webhook e la Risposta Webhook che siano lenti. Il chiamante potrebbe andare in timeout prima dell'invio della risposta

Le variabili appaiono come {variable_name} grezzo nel body della risposta

1. Conferma che la variabile sia stata impostata da un blocco precedente nello stesso flusso
2. I nomi delle variabili sono sensibili alle maiuscole. Controlla l'ortografia
3. Per i campi annidati, usa la notazione con punto: {customer.email}, non {customer_email}
4. Se la variabile proviene dal payload del webhook in arrivo, assicurati che il payload contenesse effettivamente il campo

Il JSON malformato viene rifiutato dai chiamanti rigorosi

1. Valida il template del body come JSON prima di salvare. Una variabile senza virgolette in un campo stringa produrrà un JSON non valido se il valore contiene virgolette o interruzioni di riga
2. Per i campi numerici come {amount}, non racchiudere tra virgolette. Per i campi stringa, racchiudi sempre: "name": "{name}"
3. Testa con una chiamata di esempio (usando curl o Postman) per vedere i byte effettivi restituiti

Mancata corrispondenza del Content-Type

1. Alcuni chiamanti richiedono esplicitamente application/json; charset=utf-8. Il predefinito invia application/json senza il charset
2. I client SOAP potrebbero richiedere text/xml anziché application/xml. Controlla la documentazione dell'integrazione

Prossimi passi

• Blocco Webhook - Ricevi chiamate HTTP in entrata per attivare o riprendere un flusso
• Blocco API - Chiama API esterne dal flusso
• Panoramica di Studio - Esplora tutti i tipi di blocco e le funzionalità del flow builder