Vai al contenuto

Webhook

Ultimo aggiornamento:

Che cos'è un webhook

Un webhook viene chiamato anche callback HTTP o API inversa. Con una normale chiamata API è il tuo programma a chiedere dati a un altro sistema. Con un webhook registri una volta un URL, scegli gli eventi che ti interessano e l'altro sistema chiama quell'URL ogni volta che uno di essi si verifica. Il messaggio è di solito una richiesta POST con un corpo JSON che descrive l'evento.

L'alternativa è il polling: interrogare un'API ogni pochi minuti per vedere se ci sono novità. Il polling spreca richieste quando non è successo nulla e ritarda gli aggiornamenti quando qualcosa è successo. I webhook evitano entrambi i problemi.

Come funziona

Un webhook coinvolge un mittente e un destinatario:

  • Il destinatario crea un endpoint, un URL sul proprio server che accetta richieste in HTTPS.
  • Nelle impostazioni del mittente registra quell'URL e sceglie gli eventi a cui iscriversi.
  • Quando si verifica un evento, il mittente invia all'URL un payload JSON con il tipo di evento e i relativi dati.
  • Il destinatario verifica che la richiesta sia autentica, risponde subito con un codice di stato 2xx e poi elabora i dati. Se non riceve una risposta di successo, il mittente di solito riprova più tardi.

Esempio

Un negozio online vuole che il suo gestionale di magazzino conosca subito ogni nuovo ordine. Invece di far interrogare il negozio dal gestionale ogni minuto, il negozio invia un webhook all'endpoint del gestionale a ogni ordine. Il payload contiene numero d'ordine, articoli e indirizzo di spedizione, così la preparazione del pacco può partire in pochi secondi.

Buone pratiche per ricevere i webhook

Un endpoint webhook è un URL pubblico, quindi tratta ogni richiesta in arrivo con attenzione:

  • Verifica la firma. Molti mittenti firmano ogni payload con un segreto condiviso, spesso tramite HMAC, così puoi confermare che la richiesta viene da loro e non è stata alterata lungo il percorso.
  • Usa HTTPS, perché i payload possono contenere dati personali e devono viaggiare cifrati.
  • Rispondi in fretta. Restituisci subito uno stato 2xx e svolgi il lavoro lento in background, altrimenti il mittente potrebbe considerare fallita la consegna.
  • Metti in conto i duplicati. I nuovi tentativi possono consegnare lo stesso evento due volte, quindi usa l'ID dell'evento per elaborarlo una sola volta. Questa proprietà si chiama idempotenza.

Perché conta per i chatbot aziendali

I webhook collegano un chatbot al resto dell'azienda senza che qualcuno debba tenere d'occhio una dashboard. Una piattaforma di chatbot può inviare un webhook quando una conversazione termina o quando viene raccolto un lead, così un CRM, un foglio di calcolo o uno strumento di automazione lo riceve subito. Quando confronti strumenti per chatbot, controlla quali eventi possono inviare e se i payload sono firmati.

I webhook in intoCHAT

intoCHAT invia webhook firmati (HMAC-SHA256) per quattro eventi: un nuovo lead (lead.created), una richiesta di passaggio a una persona (handoff.requested), l'invio di un modulo in chat (form.submitted) e un appuntamento prenotato (booking.created). Ogni agente può inviarli fino a 5 endpoint https, le consegne non riuscite vengono ritentate e un registro delle consegne mostra cosa è stato inviato. Funzionano con il tuo server o con strumenti che accettano webhook in entrata, come Zapier, Make o n8n. intoCHAT ha anche una propria app per Zapier (dal piano Starter); non c'è ancora un'app per Make o n8n. I nuovi lead ti arrivano anche con un'email di notifica, inviata al titolare e fino a 5 altri indirizzi, e nella tabella dei lead, da cui puoi esportarli in CSV.

Le azioni API personalizzate di intoCHAT funzionano in modo diverso dai webhook. L'agente chiama la tua API HTTP durante la chat quando la conversazione lo richiede, per esempio per verificare un prezzo o una disponibilità, non automaticamente a ogni evento. Servono a portare dati aggiornati nelle risposte; per inoltrare i lead a un altro sistema ci sono i webhook.

Domande frequenti

Che differenza c'è tra un webhook e un'API?

Un'API aspetta la tua richiesta e risponde. Un webhook ti invia i dati di sua iniziativa quando si verifica un evento. In pratica lavorano insieme: il webhook segnala che è successo qualcosa e il tuo sistema può chiamare l'API per avere più dettagli.

I webhook sono sicuri?

Possono esserlo, se il destinatario fa la sua parte. Usa un endpoint HTTPS, verifica la firma che il mittente aggiunge a ogni payload e rifiuta le richieste che non superano il controllo. Conserva il segreto condiviso sul server e sostituiscilo se viene esposto.

Cosa succede se il mio endpoint webhook non risponde?

La maggior parte dei mittenti ripete le consegne fallite per un certo periodo, e alcuni disattivano il webhook dopo errori ripetuti. Poiché i nuovi tentativi possono consegnare lo stesso evento più volte, salva gli ID degli eventi e salta quelli già elaborati.

intoCHAT supporta i webhook?

Sì. intoCHAT invia webhook firmati, con nuovi tentativi e registro delle consegne, per nuovi lead, richieste di passaggio a una persona, moduli inviati in chat e appuntamenti prenotati. Puoi riceverli sul tuo server o in Zapier, Make o n8n tramite i loro trigger per webhook in entrata. Dal piano Starter, l'app Zapier di intoCHAT può anche avviare uno Zap per ogni nuovo lead; non c'è ancora un'app per Make o n8n.

Guardalo rispondere dal tuo sito

Incolla l’indirizzo del tuo sito e chatta con un agente creato dalle tue pagine. Ci vuole circa un minuto.

Crea il tuo agente gratis

Piano gratuito, nessuna carta di credito.