Webhook per Zapier e Make

Perché un webhook e non un'app pronta in Zapier

Fino ad aprile 2024 esisteva una via ufficiale: Facebook Groups API, su cui si basavano il trigger «New Post in Group» in Zapier e il modulo corrispondente in Make. Meta l'ha disattivata senza offrire nulla in sostituzione. L'app Facebook in Zapier esiste ancora, ma gestisce pagine e annunci: i gruppi sono spariti dalla lista dei trigger e non torneranno, perché non esiste più l'interfaccia su cui potrebbero basarsi.

LeadScanner legge gruppi pubblici e pagine Facebook senza account, come li vede un passante non connesso, e dopo ogni scansione può inviare un evento all'indirizzo indicato. Dal punto di vista di Zapier e Make è un normale webhook in entrata, cioè esattamente il trigger che manca. Il resto è ciò che questi strumenti fanno bene: una riga in un foglio, una scheda nel CRM, un messaggio su Slack, un'attività per il commerciale.

Il canale webhook è disponibile nel piano Growth e superiori. Lo configura il proprietario o l'amministratore dell'organizzazione nel pannello, nella scheda Notifiche → Canali.

Configurazione in Zapier

In Zapier crea un nuovo Zap e come trigger scegli l'app «Webhooks by Zapier», evento «Catch Hook». Zapier mostrerà l'indirizzo su cui ascolta: copialo. Non chiudere questa scheda, ci tornerai tra poco.

Nel pannello LeadScanner apri Notifiche → Canali e aggiungi un canale Webhook. Incolla l'indirizzo copiato. Se vuoi che dall'altra parte si possano distinguere i tuoi eventi da quelli altrui, aggiungi un'intestazione di autenticazione: un nome, per esempio X-Api-Key, e un valore che scegli tu. È facoltativo, ma costa poco e conviene farlo subito.

Seleziona gli eventi da inviare: «Nuovi lead», «Scansione terminata» o entrambi. Per l'automazione delle vendite di solito basta il primo; il secondo è utile se vuoi registrare ogni scansione, anche vuota. Salva il canale e fai clic su «Invia test».

Torna in Zapier e fai clic su «Test trigger». Zapier riceverà l'evento di test e lo suddividerà nei campi che da questo momento puoi mappare nei passaggi successivi: person_name nella colonna del nome, post_url nel link, score nella priorità. L'evento di test ha il campo test impostato su true e dati di esempio: non inserire questa persona nel CRM, perché non esiste.

Configurazione in Make

In Make aggiungi allo scenario il modulo «Webhooks» → «Custom webhook», assegnagli un nome e copia l'indirizzo generato. Da questo momento Make ascolta e attende il primo messaggio per leggerne la struttura dei dati.

I passaggi nel pannello LeadScanner sono gli stessi di Zapier: Notifiche → Canali → Webhook, incolla l'indirizzo, aggiungi facoltativamente un'intestazione di autenticazione, scegli gli eventi, salva e fai clic su «Invia test».

Dopo il test Make mostrerà di aver riconosciuto la struttura. Se non lo vedi, ad esempio perché il webhook era già in ascolto e ha memorizzato una forma diversa, fai clic nel modulo su «Redetermine data structure» e invia di nuovo il test. Da questo momento i campi del payload sono disponibili in ogni modulo successivo dello scenario.

Una nota pratica per entrambi gli strumenti: l'evento «Nuovi lead» contiene un elenco, non un singolo lead. In Make dividilo con un iteratore, in Zapier usa il passaggio «Looping by Zapier» oppure mappa solo il primo elemento, se reagisci comunque all'intero blocco in una volta sola.

Evento new_leads: cosa ricevi

Ogni evento è una richiesta POST con corpo in formato JSON. In cima c'è sempre lo stesso insieme di campi: event — nome dell'evento, qui new_leads; version — numero di versione del formato, oggi 1; organization_id — identificatore della tua organizzazione; sent_at — ora di invio in ISO 8601; subject — titolo di una riga, lo stesso che compare nell'oggetto dell'e-mail; leads_count — numero di lead nel blocco; leads — elenco di lead.

Ogni elemento dell'elenco leads contiene: person_name — nome e cognome dell'autore del post, come appare su Facebook; score — valutazione da 0 a 100, più è alto, più la richiesta è certa; excerpt — frammento del post o commento in cui è stata posta la domanda; post_url — link al post; profile_url — link al profilo dell'autore, se visibile, altrimenti null; rationale — una frase sul perché questo post è stato considerato un lead; source_name — nome del gruppo o della pagina in cui è apparso.

L'invio di test ha esattamente questa struttura, solo con dati di esempio e un campo aggiuntivo test impostato su true. È il modo più semplice per vedere un esempio completo: fai clic su «Invia test» e guarda in Zapier o Make cosa è arrivato.

Evento scan_finished: lo stesso più la scansione

L'evento scan_finished include tutti i campi descritti sopra — con l'elenco dei lead trovati in questa scansione, che può essere vuoto — e inoltre l'oggetto scan. Al suo interno: id — identificatore della scansione; source_id, source_name e source_url — quale fonte è stata controllata; status — come si è conclusa; mode — modalità, parole chiave o IA; scheduled_slot — slot di pianificazione a cui apparteneva la scansione; started_at e finished_at — ora di inizio e fine; points_spent — quanti punti è costata; leads_found — quanti lead ha trovato; error e error_code — descrizione e codice dell'errore, se la scansione è fallita, altrimenti null.

Inoltre coverage, cioè il resoconto di ciò che la scansione ha esaminato: posts_seen e comments_seen — quanti post e commenti ha letto; posts_suppressed — quanti post ha saltato perché i loro autori hanno chiesto la rimozione dei propri dati; posts_stale e comments_stale — quanti erano più vecchi della finestra di aggiornamento; posts_unchanged e comments_unchanged — quanti conosceva già dalla scansione precedente e non ha valutato di nuovo; graded — quanti elementi sono stati valutati; leads — quanti sono diventati lead; rejected — elenco di coppie reason e count, cioè per quali motivi e quanti sono stati scartati.

I numeri in coverage tornano sempre: graded sono i post e i commenti recenti, al netto di quelli vecchi e già noti, e leads più la somma di rejected dà graded. Se costruisci una dashboard su questi dati, puoi fare affidamento su queste due identità.

I motivi in rejected provengono sempre dallo stesso elenco: no_keyword (non è stata usata alcuna parola chiave), no_intent (non si può stabilire se l'autore stia cercando qualcosa), not_in_market (usa il linguaggio del settore, ma non sta acquistando — dà consigli, racconta, vende), outside_offer (acquista, ma non ciò che offri o non dove operi), excluded (chiede esattamente ciò che non fai), below_threshold (corrisponde, ma troppo poco per la soglia), ungraded (il modello ha risposto in un formato non leggibile). Considerali come un dizionario, senza mapparli a intuito.

Firma HMAC e alternative

Se imposti un segreto nel canale, ogni richiesta riceverà due intestazioni: X-LeadScanner-Timestamp con l'ora della firma in secondi Unix e X-LeadScanner-Signature con il valore v1=<hex>, dove hex è l'HMAC-SHA256 della stringa “<timestamp>.<ciało>” calcolato con il tuo segreto. Il destinatario calcola lo stesso valore dal proprio lato e lo confronta; rifiuta una firma più vecchia di cinque minuti. Così nessuno che conosca solo l'indirizzo può fingere di essere LeadScanner né riprodurre una richiesta intercettata una settimana dopo.

Senza segreto non ci sono intestazioni di firma: l'evento viene inviato senza firma, come nella maggior parte delle integrazioni no-code. Zapier e Make non calcolano HMAC senza un passaggio aggiuntivo di codice, quindi per loro una protezione più semplice e sufficiente è l'intestazione di autenticazione nel pannello: sul lato dell'automazione aggiungi un filtro che lasci passare solo le richieste con quel nome e quel valore.

Due regole che non puoi disattivare: l'indirizzo deve essere HTTPS pubblico — il normale http o un indirizzo nella rete locale non funzionano — e i reindirizzamenti vengono rifiutati. Se il tuo server risponde con 301 o 302, la consegna termina con un errore invece di passare silenziosamente a un altro indirizzo, perché a quell'altro indirizzo la firma e l'intestazione di autenticazione finirebbero dove non dovrebbero.

Quando la consegna non riesce

Una risposta diversa da 2xx, un timeout o una connessione interrotta indicano un tentativo non riuscito. Non ci fermiamo lì: inviamo di nuovo l'evento tre volte, con intervalli crescenti — il primo tentativo dopo mezzo minuto, l'ultimo dopo alcuni minuti. È sufficiente per attendere il riavvio del server o un limite temporaneo lato Zapier, mentre la notifica che alla fine arriva resta una notifica, non una cronaca.

Ogni tentativo — riuscito o meno — è visibile nel pannello, sotto il canale, con orario, codice di risposta e motivo dell'errore. Se dopo quattro tentativi l'evento non è arrivato, resta in questo elenco come non riuscito ed è lì che devi iniziare a cercare: di solito si tratta di un indirizzo Zapier che non esiste più o di uno scenario in Make che qualcuno ha disattivato.