Contare gli Obiettivi della Prova (webhook eventi)
Quasi sempre una prova si giudica su un numero: dieci appuntamenti fissati, tre contratti chiusi, cinquanta lead consegnati. Il webhook eventi prova è un indirizzo che il tuo gestionale chiama ogni volta che quel numero cresce di uno: SalesControl tiene il conto al posto tuo e, quando l’obiettivo è raggiunto, segna la prova come superata senza che nessuno debba ricordarsene.
L’indirizzo è uno solo per tutta l’agenzia: lo configuri una volta e lo riusi nel workflow di ogni cliente, snapshot GoHighLevel compresi. A capire di quale cliente si tratta ci pensa SalesControl, leggendo quello che il messaggio porta con sé.
Questa funzione richiede un piano a pagamento (dal piano Starter in su). Vedi i Piani di Abbonamento.
Dove si configura
Apri il Pannello Admin e vai alla scheda Integrazioni: la card Eventi prova (webhook) è riservata agli admin. L’obiettivo e la finestra, invece, si impostano dove vivono i contratti: nella pagina Servizi e nel modulo del cliente.
Creare l’indirizzo
Finché non lo fai, la card dice che non c’è nessun indirizzo. Un clic crea il token dell’agenzia e mostra l’indirizzo completo, che finisce con /functions/v1/trial-events?t=a1b2c3…: la parte dopo t= è il token.
Il pulsante Copia indirizzo mette negli appunti l’indirizzo completo, token compreso. È lo stesso per tutti i clienti: non serve crearne uno per ognuno.
In GoHighLevel: Automazioni › Workflow › aggiungi l’azione Webhook con metodo POST nel punto in cui l’evento accade (per esempio dopo un appuntamento fissato). In Zapier o Make: modulo Webhooks, metodo POST, e componi il corpo JSON con i campi qui sotto.
Nella card, la voce Come si collega (GHL / Zapier / Make) apre le istruzioni insieme a due corpi JSON pronti da copiare, uno per GoHighLevel e uno per Zapier o Make.
I campi accettati
Il requisito minimo è che arrivi almeno la chiave esterna oppure il nome del cliente: senza nessuno dei due il messaggio viene rifiutato, perché non ci sarebbe modo di capire a chi appartiene l’evento. Tutto il resto è facoltativo.
| Campo | Chiavi riconosciute | A cosa serve |
|---|---|---|
| Chiave esterna | external_id, location_id, source_id | Un identificatore stabile del cliente nel tuo gestionale. In GoHighLevel è {{location.id}}. |
| Nome del cliente | client_name, location_name, business_name, nome_business, name, nome | Il nome con cui il cliente è registrato in SalesControl. Serve al primo aggancio. |
| Etichetta dell’evento | event, evento, event_label, event_type, tipo_evento | Testo libero che compare nel registro. Nei template è goal: puoi lasciarlo o scriverci l’unità che conti. Non cambia il conteggio. |
| Id dell’evento | event_id, idempotency_key | L’identificatore dell’appuntamento o del contratto: evita che lo stesso evento venga contato due volte. |
| Data dell’evento | occurred_at, event_date, data_evento, date, data, timestamp | Quando è successo. Se manca o non è leggibile si usa il momento della ricezione. |
I nomi delle chiavi si leggono senza distinzione tra maiuscole e minuscole, quindi LOCATION_ID vale quanto location_id. Gli underscore, però, non vengono ignorati: le forme camelCase riconosciute sono solo quelle con un alias esplicito — locationId, sourceId, clientName, locationName, businessName, eventId, idempotencyKey. Per tutti gli altri campi usa la forma con underscore: occurred_at, event_date, event_type. Le date sono accettate sia come GG/MM/AAAA sia come AAAA-MM-GG; se il formato non è riconosciuto l’evento viene comunque registrato, con la data di ricezione.
Il formato di GoHighLevel
GHL non manda i campi tutti allo stesso livello: i valori personalizzati del workflow finiscono dentro customData. Il webhook legge sia customData, sia il livello principale, sia contact. In caso di doppioni vince customData, poi il livello principale, infine contact — ma un campo personalizzato lasciato vuoto non cancella il valore standard con lo stesso nome.
Non contare due volte lo stesso evento
Quando un’automazione non riceve risposta in fretta, tende a ri-provare: senza precauzioni lo stesso appuntamento verrebbe contato più volte e la prova risulterebbe superata in anticipo. Per questo conviene mandare sempre event_id con l’identificatore dell’appuntamento o del contratto: se lo stesso identificatore torna una seconda volta, SalesControl risponde ok ma non incrementa il conteggio.
La stessa protezione copre l’errore più comune quando si configurano molte automazioni: lo stesso indirizzo incollato in due o tre workflow diversi che scattano sullo stesso fatto. Anche in quel caso l’evento arriva più volte, ma con event_id valorizzato viene contato una volta sola. Senza event_id, invece, SalesControl non ha modo di sapere che si tratta dello stesso fatto e conta ogni chiamata.
Contare un evento da un tag GoHighLevel
Con l’app GoHighLevel collegata non serve nessun workflow: il tag che conta per la prova si imposta come regola nella card Eventi da tag GoHighLevel (Admin › Integrazioni › Webhook), con ambito Sotto-account dei clienti e azione Conta per la prova. La card Eventi prova (webhook) ti ci rimanda con il link Vai alle regole; un tag che avevi già impostato lì è diventato una regola da solo. Ogni volta che un contatto del sotto-account di un cliente con la prova in corso riceve quel tag, la prova conta un evento: per contare di nuovo lo stesso contatto, il workflow deve togliere e rimettere il tag. Vale solo per i clienti con il sotto-account collegato. Nel registro eventi della scheda cliente questi eventi portano il badge Tag GHL. Obiettivo, finestra e chiusura della prova restano quelli di sempre, e l’indirizzo del webhook continua a funzionare per chi non usa GoHighLevel.
Come l’evento trova il cliente
All’arrivo, ogni evento viene abbinato a un cliente in due passaggi:
- se la chiave esterna è già collegata a un cliente, l’abbinamento è immediato;
- altrimenti si confronta il nome, ignorando maiuscole, accenti e spazi doppi. Un solo cliente corrispondente: abbinato. Più clienti con lo stesso nome, oppure nessuno: l’evento resta in attesa e finisce nella riconciliazione.
Il primo abbinamento riuscito impara il collegamento: la chiave esterna viene salvata sul cliente e da quel momento gli eventi successivi lo trovano subito, anche se il nome nel tuo gestionale cambia. Un cliente che ha già una chiave non viene mai riagganciato in silenzio a un’altra.
Gli eventi rimasti senza cliente
Quando ci sono eventi in attesa, in cima alla pagina Clienti compare una fascia gialla — visibile solo agli admin — con il conteggio e il pulsante Sistema ora. Si apre la finestra Eventi prova da associare, dove per ogni evento vedi il nome e la chiave arrivati, la data e, per i casi ambigui, i clienti candidati.
- Assegna collega l’evento al cliente che scegli. Se l’evento portava una chiave esterna, quella chiave viene collegata a questo cliente (e staccata da eventuali altri): gli eventi successivi si aggancieranno da soli.
- Ignora archivia l’evento: resta registrato ma non conta per nessuno.
- La spunta Applica a tutti gli eventi con la stessa provenienza, attiva di default, vale solo per Assegna: collega in un colpo solo allo stesso cliente anche tutti gli altri eventi in attesa arrivati con la stessa chiave o lo stesso nome. È il motivo per cui non perdi nulla anche se il webhook parte prima che il cliente esista in SalesControl. Ignora, invece, agisce sempre su un evento alla volta: se ne hai molti da scartare, li archivi uno per uno.
Obiettivo e finestra: dove si impostano
Due valori governano l’esito automatico, e vivono su due livelli:
| Dove | Campi | Effetto |
|---|---|---|
| Servizi (il modello) | Obiettivo eventi prova, Finestra prova (giorni) | I valori predefiniti per tutti i clienti che partono con quel servizio. |
| Scheda del cliente (nel modulo, se la casella Prova è attiva) | Gli stessi due campi | Valgono solo per quel cliente. Lasciandoli vuoti si usano quelli del servizio. |
In creazione i due campi si precompilano con i valori del servizio che scegli; in modifica mostrano quelli attualmente impostati sul cliente.
Senza obiettivo gli eventi vengono comunque contati e mostrati: semplicemente non chiudono mai la prova da soli. È il modo più comodo per iniziare a misurare prima di decidere quale sia la soglia giusta.
La finestra non parte dalla firma, ma dal giorno in cui premi 🚀 Attiva campagne nella lista Clienti: finché non lo fai non esiste nessuna scadenza. Vedi Gestione del Periodo di Prova.
Cosa vedi mentre la prova va avanti
- Nella lista Clienti, la colonna Prova mostra un badge di avanzamento tipo 7/10 · 12g: eventi raccolti su obiettivo, e giorni che restano di finestra. Se la finestra non è ancora partita restano solo i due numeri e il tooltip ricorda di attivare le campagne; quando la finestra è partita, il tooltip mostra fino a quando è valida.
- Nella scheda del cliente, la card Eventi della prova mostra conteggio, barra di avanzamento e data di fine finestra, con il Registro eventi che si apre con un clic ed elenca ogni evento con la sua data, l’etichetta e la provenienza (Webhook o Manuale).
L’etichetta che vedi in ogni riga del registro è esattamente il testo che hai messo nel campo event: nei template è goal, e va benissimo lasciarlo così. Se preferisci, scrivici l’unità che stai contando — appuntamento, contratto, lead — così chi legge il registro capisce al volo di cosa si tratta. Sul conteggio non cambia nulla: ogni evento vale +1, qualunque etichetta porti.
Gli admin possono correggere il conteggio: Aggiungi un evento a mano registra un evento che il gestionale non ha mandato, mentre il cestino su una riga la esclude — l’evento resta nel registro come traccia, ma smette di contare.
Un evento agganciato a un cliente viene sempre contato, anche se arriva prima dell’attivazione campagne o quando la prova è già chiusa. Sono l’obiettivo e la finestra a decidere l’outcome, mai il conteggio.
Quando l’obiettivo viene raggiunto
Se il cliente ha una prova in corso e il conteggio arriva all’obiettivo, la prova viene chiusa come superata in automatico, con gli stessi effetti del pulsante manuale: il contratto diventa attivo (le scadenze delle rate restano quelle calcolate alla firma), scattano gli eventuali bonus retroattivi legati al mese di firma e la chiusura viene registrata nella timeline del cliente come azione di sistema.
Quando invece l’obiettivo viene raggiunto grazie a una correzione manuale, la card mostra il pulsante Segna prova superata: la chiusura resta una tua decisione, con gli stessi effetti.
Quando la finestra scade senza obiettivo
Il controllo gira una volta al giorno e il comportamento lo decidi tu, con la casella Fallimento automatico a fine finestra nella card:
- Spenta (impostazione di partenza): ricevi una sola notifica “finestra scaduta” e decidi tu se chiudere la prova o darle altro tempo. L’avviso non si ripete nei giorni successivi.
- Accesa: la prova viene chiusa come fallita, esattamente come se avessi premuto tu il pulsante — valore del contratto azzerato, rate pendenti rimosse, voce nello storico.
Se il fallimento automatico è spento e la notifica Finestra Prova Scaduta è disattivata su entrambi i canali, allo scadere della finestra non succede nulla: la prova resta aperta e te ne accorgi solo dal badge nella lista. Se conti sull’avviso, accendilo.
Le notifiche
Tre notifiche seguono il ciclo di vita della prova, e sono disattivate di default su entrambi i canali. Le accendi in Pannello Admin › Notifiche:
| Notifica | Quando parte |
|---|---|
| Prova Superata | La prova viene superata, sia per obiettivo raggiunto sia per chiusura manuale. |
| Prova Fallita | La prova viene chiusa come fallita, per fallimento automatico o manualmente. |
| Finestra Prova Scaduta | La finestra finisce senza obiettivo raggiunto, con il fallimento automatico spento. |
I destinatari si scelgono canale per canale tra setter, closer, PM assegnato, admin e sales manager. Il cliente è disponibile solo via email, perché non ha notifiche push: se non ha un indirizzo email in scheda, viene semplicemente saltato.
Gestire l’indirizzo nel tempo
- La card mostra quanti eventi sono stati registrati in tutta l’agenzia — quelli aggiunti a mano e quelli ignorati compresi — e quando l’indirizzo è stato usato l’ultima volta: è il modo più veloce per capire se l’integrazione è viva.
- Disattiva sospende l’indirizzo senza cancellarlo: le chiamate smettono di funzionare finché non lo riattivi. Gli eventi già ricevuti restano.
- Rigenera token crea un indirizzo nuovo e invalida il precedente: dovrai incollare quello nuovo in tutti i workflow collegati, altrimenti smettono di consegnare.
L’indirizzo contiene un token: chi lo possiede può far crescere il conteggio delle prove della tua agenzia, e quindi farle risultare superate. Non può leggere né modificare nient’altro. Trattalo come una credenziale, condividilo solo con chi configura le automazioni e, se finisce nel posto sbagliato, usa Rigenera token.
Se qualcosa non funziona
- Il tuo strumento riceve un 404: l’indirizzo è sbagliato o incompleto, il token non esiste più (rigenerato) oppure l’indirizzo è disattivato.
- Errore 403: l’agenzia è sul piano Free, che non include il webhook eventi prova.
- Errore 422: nel messaggio non c’erano né la chiave esterna né il nome del cliente. Controlla che i valori personalizzati del workflow siano davvero valorizzati.
- Il conteggio non sale ma nella card gli eventi ricevuti aumentano: gli eventi stanno arrivando ma non trovano il cliente. Guarda la fascia gialla nella pagina Clienti e assegnali.
- Il conteggio sale troppo in fretta: probabilmente il tuo strumento sta ri-provando lo stesso evento. Aggiungi
event_idal corpo del messaggio. - L’obiettivo è raggiunto ma la prova non si chiude: succede quando la prova è già stata chiusa, oppure quando l’obiettivo è stato raggiunto con eventi aggiunti a mano o assegnati dalla coda di riconciliazione — solo gli eventi che il webhook aggancia da sé chiudono la prova in automatico, negli altri casi usa Segna prova superata nella card.
- Il badge di avanzamento non compare: quel cliente non ha un obiettivo impostato, né sul suo modulo né sul servizio, oppure la sua prova è già chiusa — superata o fallita che sia. Il badge accompagna solo le prove in corso.