Find Contact in HighLevel: collegare un webhook al contatto corretto prima di proseguire

TL;DR: quando un workflow HighLevel parte da un evento senza un contatto già associato, ad esempio un Inbound Webhook con email o identificativo esterno nel payload, l’azione Find Contact cerca il record CRM corrispondente e crea due percorsi: Contact Found e Contact Not Found. Il risultato operativo verificabile è che le azioni successive possono essere progettate separatamente per un contatto trovato e per un contatto assente, invece di proseguire senza una logica esplicita di associazione.

In sintesi

Il problema tipico non è ricevere un webhook: è capire a quale contatto debba appartenere ciò che il webhook comunica. Un responsabile che gestisce automazioni può ritrovarsi con un evento in ingresso contenente un’email, un numero di telefono o un ID cliente, ma senza un contatto HighLevel già agganciato al workflow. Se prosegue senza una ricerca strutturata, diventa più difficile decidere se aggiornare un record esistente, creare un nuovo record o fermare il flusso per una verifica.

L’azione Find Contact di HighLevel è pensata proprio per workflow avviati senza contatto, ma con informazioni identificative disponibili. Secondo la documentazione ufficiale di HighLevel, supporta campi standard, campi personalizzati e riferimenti esterni memorizzati in campi custom. Quando la ricerca termina, espone i rami Contact Found e Contact Not Found.

Questo tutorial è utile a chi configura integrazioni, webhook in entrata e trigger di app che trasmettono merge field, in particolare quando il CRM deve collegare un evento a un record già presente. Nomi delle azioni, opzioni e disponibilità nell’interfaccia possono cambiare dopo la data di verifica della fonte ufficiale.

La situazione di partenza

Risposta breve: un webhook può avviare un workflow senza sapere ancora quale record CRM aggiornare. Find Contact serve a trasformare un dato identificativo ricevuto, come un’email, nell’associazione con il contatto giusto prima delle azioni successive.

Immaginiamo uno scenario ipotetico: un’azienda riceve tramite webhook informazioni da uno strumento esterno. Nel payload arrivano l’email della persona e un dato relativo a un acquisto, a una prenotazione o a un abbonamento. Il trigger Inbound Webhook può ricevere uno o più query parameter; tuttavia, se questi parametri non contengono un user ID ma includono un’email o un altro identificativo, il workflow non parte necessariamente con un contatto già definito.

Nel processo manuale, qualcuno dovrebbe leggere il dato ricevuto, cercare il contatto nel CRM, controllare se è quello corretto e decidere cosa fare quando non esiste. Oltre al tempo richiesto, questo passaggio introduce un rischio concreto: aggiornare il record sbagliato, creare record duplicati o lasciare l’evento senza seguito perché il caso “contatto non trovato” non è stato previsto.

HighLevel colloca Find Contact nella logica dei workflow contactless: il workflow riceve l’evento, cerca il contatto sulla base di criteri scelti e separa il seguito in base all’esito. Non è una garanzia che il dato in ingresso sia corretto o univoco; è uno strumento per rendere la ricerca e la gestione dell’assenza di corrispondenza esplicite nel workflow.

La scelta del criterio è quindi il punto operativo più importante. La documentazione raccomanda di preferire identificativi univoci e di mantenere coerente la formattazione dei dati in entrata. Email e telefono sono campi standard disponibili per la ricerca; un Customer ID, un Referral Code o uno Stripe Customer ID possono invece essere gestiti come riferimenti esterni, mappandoli su un campo personalizzato del contatto.

Cosa cambia con HighLevel

Risposta breve: il workflow passa da un evento senza contatto a due percorsi dichiarati, uno per il record trovato e uno per il record assente. Questo rende configurabile ciò che prima sarebbe una ricerca manuale o una decisione implicita.

Con Find Contact, HighLevel consente di identificare un contatto nel database usando criteri specificati dall’utente. I campi utilizzabili comprendono:

• campi standard, tra cui Email, Phone, First Name e Last Name;
• campi personalizzati già creati e valorizzati sui contatti;
• riferimenti esterni, per esempio un ID cliente di un sistema di pagamento salvato in un campo custom.

Il vantaggio non è “trovare sempre” un contatto, bensì progettare il workflow intorno a un esito determinato. Se il contatto viene trovato, si possono collocare in quel ramo azioni coerenti con un record esistente, come l’aggiornamento di un campo, l’aggiunta di un tag o l’invio di un’email. Se non viene trovato, il ramo Contact Not Found può contenere l’azione appropriata, per esempio Create Contact, come indicato negli esempi della fonte.

Questa distinzione è utile anche per chi ha già workflow che aggiornano opportunità. L’associazione al contatto e l’identificazione dell’opportunità sono problemi diversi: dopo aver risolto il primo, può essere pertinente valutare una logica dedicata per il secondo, come spiegato nel nostro tutorial su Find Opportunity in HighLevel.

C’è però una regola che cambia il modo di progettare i criteri: quando si selezionano più campi, HighLevel applica una logica AND. Devono quindi corrispondere tutti i valori specificati. Email più telefono più campo custom non amplia la ricerca: la restringe. È utile per aumentare la precisione quando i dati sono affidabili e coerenti; può invece portare a Contact Not Found se anche un solo valore ricevuto è diverso, mancante o formattato in altro modo.

La fonte segnala inoltre un’opzione per includere indirizzi email o numeri telefonici aggiuntivi. Per impostazione predefinita, la ricerca confronta soltanto il campo Email o Phone principale del contatto. Se il database conserva email o telefoni aggiuntivi, è possibile abilitarne l’inclusione dopo aver scelto il rispettivo campo standard.

Come configurare il flusso

Risposta breve: inserisci Find Contact dopo un trigger che fornisce dati identificativi, scegli un criterio affidabile, poi costruisci e testi entrambi i rami. I passaggi seguenti riprendono le indicazioni della fonte ufficiale; la posizione esatta dei comandi può variare nell’interfaccia di GoHighLevel.

1. Parti dal trigger e leggi quali dati arrivano

Nel builder dei workflow, accedi alla sezione Automation del CRM e crea un workflow oppure aprine uno esistente. La documentazione cita Inbound Webhook come caso tipico: il trigger riceve un payload con parametri che possono includere email o altri identificativi, pur non avendo un user ID.

Prima di definire la ricerca, il consiglio editoriale è annotare i valori realmente disponibili nel trigger: non scegliere un campo solo perché esiste nel CRM. Se il webhook fornisce un’email, la ricerca per Email è il punto di partenza indicato dalla fonte. Se trasmette un ID cliente stabile, ha più senso valutare un campo personalizzato dedicato a quell’ID.

La fonte indica anche che, oltre a Inbound Webhook, i merge field necessari possono arrivare tramite un custom App Marketplace trigger creato da sviluppatori terzi. In ogni caso, il requisito operativo resta lo stesso: il trigger deve rendere disponibile l’informazione che userai per identificare il contatto.

2. Aggiungi e nomina l’azione Find Contact

Nel workflow, seleziona l’icona + e scegli l’azione Find Contact dall’elenco. Assegna un nome descrittivo, per esempio “Trova contatto per email”. Questo non modifica la logica di match, ma rende più leggibile il workflow quando dovrai rivederlo o quando lo gestirà un’altra persona.

3. Seleziona il campo di corrispondenza

Scegli i campi standard necessari, come Email o Phone, oppure individua il campo personalizzato che contiene un valore univoco. Se il campo custom non è stato creato o non è popolato sul contatto, non può essere una base affidabile per il match: è una condizione esplicitamente richiamata dalla documentazione.

Un esempio ufficiale è l’uso di uno Stripe Customer ID: il dato proveniente da webhook o app viene mappato su un custom field e Find Contact usa quel campo per localizzare il record CRM corrispondente. Lo stesso schema può essere applicato a Customer ID o Referral Code, purché il dato esista e sia salvato in modo coerente.

Se selezioni Email o Phone e il tuo archivio usa anche valori aggiuntivi, abilita l’opzione per includerli nella ricerca. Ricorda: senza questa opzione, la ricerca usa solo l’email o il numero principale.

4. Restringi i criteri solo quando serve

Puoi configurare più campi, ma devono combaciare tutti. La fonte suggerisce di rendere più specifici i criteri quando più contatti potrebbero corrispondere, aggiungendo per esempio email o un ID esterno. È una misura per ridurre ambiguità, non una scorciatoia per compensare dati incompleti.

Consiglio editoriale: usa più campi soltanto se il sistema mittente li invia con qualità e formati prevedibili. Se un webhook invia l’email ma non sempre il telefono, aggiungere il telefono al match può generare falsi “non trovati”. Quando il problema è la presenza di duplicati, la fonte rimanda anche alle preferenze di deduplicazione e alle procedure di merge dei contatti.

5. Costruisci entrambi i rami, non solo quello positivo

Dopo Find Contact, configura il ramo Contact Found. Negli esempi ufficiali, qui possono rientrare Update Contact Field, Add Tag, Send Email oppure azioni collegate all’evento ricevuto, come aggiornare piano, stato o informazioni di prenotazione.

Configura anche Contact Not Found. La documentazione propone, tra le possibili azioni, Create Contact e la prosecuzione del flusso. La scelta dipende dal processo: se l’evento deve generare un nuovo contatto, puoi progettare quel ramo per crearlo e salvare l’identificativo ricevuto; se invece il dato dovrebbe riferirsi soltanto a record già esistenti, il ramo deve comunque gestire deliberatamente l’eccezione secondo le regole interne.

Se nel ramo Contact Found prevedi l’invio di email, la ricerca del contatto non sostituisce la configurazione della deliverability. Per il contesto tecnico del mittente, consulta la guida su SPF, DKIM e DMARC in HighLevel.

6. Testa, salva e pubblica

La fonte indica di validare la configurazione usando dati di test, salvare l’azione e pubblicare il workflow. Il test dovrebbe comprendere almeno un caso che trova il contatto e uno che non lo trova: sono entrambi risultati previsti dall’azione.

Non è possibile dedurre dalla sola configurazione che ogni futuro payload funzionerà allo stesso modo. Verifica quindi che i valori in ingresso rispettino il criterio scelto e che le azioni sotto ciascun ramo siano quelle desiderate prima di abilitare l’automazione.

Il risultato operativo

Risposta breve: ogni evento ricevuto può essere instradato in modo esplicito in base alla presenza o all’assenza del contatto cercato. Il workflow non deve più trattare questi due casi come se fossero identici.

In uno scenario con webhook, il risultato osservabile è una sequenza chiara: arriva il payload, Find Contact confronta i criteri configurati con il database HighLevel e il workflow continua nel ramo Contact Found oppure Contact Not Found. Nel primo caso puoi eseguire attività sul record individuato; nel secondo puoi creare il contatto o applicare una diversa gestione prevista dal processo.

Questo è particolarmente utile nelle integrazioni in cui il sistema esterno identifica la persona tramite email o identificatore proprietario. HighLevel svolge il ruolo di CRM e orchestratore del workflow; il webhook o il trigger di app porta il dato; il settore non determina la funzione, perché la stessa struttura può riguardare un ordine online, un aggiornamento di abbonamento, una prenotazione o una segnalazione da partner.

Il beneficio pratico è la tracciabilità della decisione nel disegno del workflow: non solo “aggiorna un contatto”, ma “aggiorna il contatto se il match soddisfa i criteri; altrimenti segui il percorso previsto per l’assenza di match”. I risultati effettivi variano in base alla qualità dei dati, alle regole CRM e al contesto dell’integrazione.

Errori e limiti

Risposta breve: Find Contact migliora la gestione della ricerca, ma non corregge identificativi mancanti, incoerenti o duplicati. La qualità del match dipende dai dati disponibili nel trigger e da quelli già presenti nel CRM.

Un primo errore è usare campi non univoci senza considerare possibili corrispondenze multiple. La fonte consiglia di rendere più specifica la ricerca con email o ID esterno quando necessario. Un secondo errore è dimenticare che più criteri seguono la logica AND: se uno solo non coincide, non verrà restituito un contatto.

Un terzo errore è ignorare Contact Not Found. Il ramo esiste proprio per progettare il caso in cui nessun record soddisfi il match. Lasciarlo senza una decisione operativa reintroduce il problema iniziale: un evento ricevuto ma non collegato in modo governato a un contatto.

Attenzione anche ai campi personalizzati: devono esistere e essere popolati sul record. Inoltre, email e telefoni aggiuntivi non rientrano nella ricerca predefinita se non abiliti l’opzione dedicata. Infine, Find Contact non è una dichiarazione di deduplicazione del database: se la qualità dell’archivio è un problema, vanno considerate le impostazioni di deduplicazione e il merge dei duplicati richiamati dalla documentazione ufficiale.

Tornando al problema del responsabile che riceve webhook senza un contatto associato, la soluzione non è aggiungere azioni a caso dopo il trigger. È definire prima come riconoscere il record e cosa fare quando quel riconoscimento fallisce. Se vuoi approfondire l’uso operativo di GoHighLevel con materiali dedicati, puoi consultare il nostro bonus WhatsApp per GoHighLevel. Risultati e configurazioni efficaci variano sempre in base al contesto.