Azione Workflow - Webhook Personalizzato (Custom Webhook)

L'azione Custom Webhook dei Workflow di GoHighLevel / Squadd ti permette di inviare dati in tempo reale a servizi esterni tramite richieste GET, POST, PUT e DELETE. Configura autenticazione, header, parametri di query e payload JSON/form per connettere CRM, app e API personalizzate — senza scrivere codice. Questo articolo spiega la configurazione, le best practice e esempi pratici per aiutarti a costruire integrazioni affidabili in modo rapido.

• Cos'è il Custom Webhook?
• Vantaggi principali del Custom Webhook
• Opzioni di autenticazione
• Metodi HTTP e componenti della richiesta
• Event vs Method (comportamento dell'interfaccia)
• Header e parametri di query
• Payload e mappatura dei campi
• Test e risoluzione dei problemi
• Come configurare il Custom Webhook
• Domande frequenti

Cos'è il Custom Webhook?

Il Custom Webhook è un'azione di Workflow in uscita che esegue una richiesta HTTP verso un URL da te scelto. Quando l'esecuzione di un Workflow raggiunge questo passaggio, GoHighLevel / Squadd assembla header, parametri e payload (inclusi i valori dinamici mappati) e invia la richiesta al sistema esterno.

Vantaggi principali del Custom Webhook

Capire in quali scenari eccelle il Custom Webhook ti aiuta a scegliere lo strumento di automazione giusto e a strutturare le richieste correttamente per il tuo provider.

• Metodi flessibili: Usa GET, POST, PUT, DELETE per adattarti a qualsiasi operazione API.

• Opzioni di autenticazione: Bearer token, API key, Basic Auth, OAuth2, oppure Nessuna autenticazione con header personalizzati.

• Mappatura precisa dei dati: I valori dinamici (es. {{contact.email}}) popolano header, parametri o body affinché ogni chiamata includa i dettagli corretti del record.

• Pattern riutilizzabili: Configura una volta, riutilizza su più Workflow con header, content type e struttura del payload coerenti.

• Risoluzione dei problemi più rapida: L'acquisizione opzionale della risposta e i log di esecuzione del Workflow semplificano test e diagnosi.

Opzioni di autenticazione

Le API esterne richiedono spesso credenziali. Scegli l'opzione supportata dal tuo provider e inserisci i segreti negli header — non negli URL — per una maggiore sicurezza.

• Bearer Token

  Usa l'header Authorization: Bearer <token>.

  Esempio di header:

Authorization: Bearer {{location.api_token}}

• API Key

  La maggior parte dei servizi si aspetta un header personalizzato (es. X-API-Key: <key>). Usa la chiave come parametro query solo se il provider lo richiede.

  Esempio con header:

X-API-Key: {{location.external_api_key}}

• Esempio con query string (solo se richiesto): ?api_key={{location.external_api_key}}

• Basic Auth

  Inserisci Username e Password nei campi Autorizzazione dell'azione. GoHighLevel / Squadd invia automaticamente l'header Authorization: Basic ... corretto.

• OAuth2

  Se il tuo provider usa OAuth2, configura prima il token in Impostazioni globali Workflow (Global Workflow Settings) → OAuth2 / Gestisci Token, poi selezionalo nell'azione. OAuth2 è consigliato per i provider che ruotano o aggiornano automaticamente i token.

• Nessuna autenticazione + Header personalizzato

  Se il tuo provider richiede un header specifico (es. X-Signature: <secret>), scegli No auth, quindi aggiungi l'header nella sezione Headers.

Metodi HTTP e componenti della richiesta

Usare il metodo corretto e collocare i dati nella parte giusta della richiesta previene errori 400/401/422 e velocizza le integrazioni.

• URL e parametri di percorso (Path Parameters): Puoi includere variabili nel percorso, es. https://api.example.com/contacts/{{contact.id}}.

• GET: Recupera dati. Il body viene solitamente ignorato — usa i parametri di query: https://api.example.com/leads?email={{contact.email}}&status=active

• POST: Crea risorse. Invia un body JSON o dati in formato form (vedi Content-Type).

• PUT: Aggiorna risorse. Di solito richiede un ID nel percorso e un body JSON.

• DELETE: Elimina risorse. Spesso include l'ID nel percorso.

• Content-Type: Valori comuni: application/json (body JSON) o application/x-www-form-urlencoded (campi form). Segui la documentazione del tuo provider.

Event vs Method (comportamento dell'interfaccia)

L'azione Custom Webhook offre due modalità di configurazione. CUSTOM espone il controllo completo (metodo, content type, body grezzo). GET/POST offrono un'esperienza semplificata. Scegli la modalità più adatta ai requisiti del tuo provider.

• Event = CUSTOM (avanzato):

  • Mostra il selettore Method (GET, POST, PUT, DELETE), il Content-Type e un editor Raw Body per JSON o altri formati.

  • Ideale quando hai bisogno di payload JSON, metodi diversi da POST, o header/content type espliciti.

• Event = POST (semplice):

  • Mostra coppie Body (Key and Value) per un payload in stile form; nessun editor Raw Body.

  • Da usare per invii semplici chiave/valore. Passa a CUSTOM se il tuo provider si aspetta JSON.

• Event = GET (semplice):

  • Nessun body nella richiesta. Usa i Query Parameters per i filtri. È disponibile Save response from this Webhook.

• Selettore Event:

  • Il menu a tendina Event controlla quali campi vengono visualizzati. Scegli CUSTOM per il controllo completo.

• Selettore variabili:

  • La piccola icona tag accanto ai campi (URL, Header, Query Params, Body) apre il selettore di valori dinamici per inserire valori come {{contact.id}}.

Header e parametri di query

Le API richiedono comunemente header e parametri di query specifici per autenticazione, content type, versioning o filtri. Mappa i valori dinamici quando necessario.

• Header (esempi):

Authorization: Bearer {{location.api_token}} Content-Type: application/json X-API-Key: {{location.external_api_key}} X-App-Version: 2024-11-01

• Parametri di query (esempi):

lead_id={{contact.id}} email={{contact.email}} source=workflow

• Evita di inserire segreti nelle query string, a meno che il tuo provider non lo richieda esplicitamente.

Payload e mappatura dei campi

I valori dinamici ti permettono di personalizzare ogni richiesta con dati di contatti, Opportunità o altri elementi del Workflow — strutturati in modo da corrispondere all'API esterna.

• Payload JSON semplice (POST / creazione):

{  "id": "{{contact.id}}",  "first_name": "{{contact.first_name}}",  "last_name": "{{contact.last_name}}",  "email": "{{contact.email}}",  "phone": "{{contact.phone}}" }

• JSON annidato:

{  "contact": {    "id": "{{contact.id}}",    "name": "{{contact.name}}",    "phones": ["{{contact.phone}}"],    "tags": ["{{contact.tag}}", "new-lead"]  } }

• Form-encoded: Imposta il Content-Type su application/x-www-form-urlencoded e fornisci coppie chiave/valore invece di JSON.

Test e risoluzione dei problemi

Validare le richieste prima di andare in produzione previene automazioni non funzionanti. Usa sia gli strumenti lato provider che i log del Workflow.

• Usa Test Workflow (in modalità bozza) con un record di esempio per attivare l'azione.

• Invia chiamate di test a strumenti come Webhook.site o collezioni Postman per verificare header, parametri e struttura del payload.

• Verifica prima le basi: URL corretto, metodo, Content-Type, header obbligatori e credenziali valide.

• Controlla i Log di esecuzione (Execution Logs) / cronologia delle esecuzioni per confermare che l'azione sia scattata e per esaminare i codici di stato.

• Se non vedi Content-Type o un editor Raw Body, verifica la selezione dell'Event. Scegli CUSTOM per payload JSON o richieste PUT/DELETE.

• Risposte HTTP comuni:

  • 400/422 Payload non valido → verifica che i campi e i tipi di dato corrispondano ai requisiti del provider.

  • 401/403 Non autorizzato/Proibito → correggi token, chiave, scope o permessi dell'account.

  • 404 Percorso/ID errato → verifica l'endpoint e le variabili di percorso.

  • 409 Conflitto/idempotenza → assicura ID univoci o segui le regole di upsert del provider.

  • 429 Limite di richieste superato → rallenta o aggiungi ritardi/tentativi in base ai limiti del provider.

  • 5xx Errore del provider → riprova più tardi e contatta il supporto del provider.

Come configurare il Custom Webhook

Una configurazione chiara e ripetibile riduce gli errori e garantisce che le richieste corrispondano alle aspettative del provider. Segui i passaggi seguenti per configurare correttamente URL, event/method, autorizzazione, header/parametri e payload prima di effettuare i test.

Apri il tuo Workflow

Vai su Automazioni (Automation) → Workflow e apri il Workflow in cui vuoi inviare dati, in modo che l'esecuzione raggiunga questa azione con il contesto del record corretto.

Aggiungi l'azione

Clicca su + Aggiungi azione → Invia dati (Send Data) → Custom Webhook per creare il passaggio che effettuerà la chiamata HTTP in uscita. Screenshot (segnaposto): Pannello azioni — Aggiungi l'azione Custom Webhook da Invia dati. Testo alternativo: Pannello delle azioni Workflow con Webhook e Custom Webhook visibili.

Assegna un nome all'azione

Dai all'azione un nome chiaro e descrittivo per semplificarne la lettura e la risoluzione dei problemi in futuro; ad esempio, Invia Lead al CRM Esterno.

Seleziona l'Event (e il Method quando applicabile)

Scegli l'Event più adatto al tuo caso d'uso. CUSTOM mostra il selettore Method (GET, POST, PUT, DELETE), il Content-Type e un editor Raw Body per JSON o altri formati. POST fornisce un'interfaccia semplice Body (Key and Value) senza editor del body grezzo. GET non ha body; usa i Query Parameters per passare i filtri. La piccola icona tag accanto ai campi apre il selettore di valori dinamici (ad esempio, {{contact.id}}).

Inserisci l'URL

Incolla l'endpoint del tuo provider e includi variabili nel percorso quando necessario, ad esempio https://api.example.com/leads/{{contact.id}}, in modo che ogni richiesta punti al record corretto.

Scegli l'autorizzazione

Seleziona il metodo di autenticazione richiesto dal provider — Bearer Token, API Key, Basic Auth, OAuth2 oppure None (con header personalizzati) — e fornisci le credenziali esattamente come indicato per evitare errori 401/403.

Aggiungi Header e parametri di query (se necessario)

Fornisci gli header obbligatori come Content-Type, Authorization e qualsiasi chiave personalizzata, e aggiungi i parametri di query per filtri GET o opzioni basate su URL; i valori dinamici come email={{contact.email}} garantiscono che ogni chiamata sia personalizzata.

Salva la risposta da questo Webhook (opzionale)

Abilita l'acquisizione della risposta, se disponibile nel tuo account, per facilitare la risoluzione dei problemi e la conservazione dei dati.

Salva e testa

Clicca su Save Action, attiva un test con un record di esempio o un endpoint sandbox come Webhook.site o Postman, e revisiona i Log di esecuzione (Execution Logs) insieme ai log del provider per verificare i codici di stato e la struttura del payload prima di andare in produzione.

Segnaposto aggiuntivi per screenshot (da aggiungere se disponibili):

• Gestione token OAuth2: Impostazioni globali Workflow → OAuth2 / Gestisci Token (token oscurato).

• Log di esecuzione che mostra una risposta 200 riuscita.

• Postman/Webhook.site che conferma la ricezione del payload.

Domande frequenti

D: Ho bisogno di un trigger specifico nel Workflow perché il Custom Webhook funzioni?

No. È possibile utilizzare qualsiasi trigger. Assicurati che le variabili mappate (es. i campi del contatto) siano presenti al momento dell'esecuzione.

D: Il mio provider richiede una lista di IP statici autorizzati. GoHighLevel / Squadd può fornirne una?

No. Usa invece l'autenticazione basata su header (Bearer/API Key/Basic/OAuth2) e condividi le credenziali richieste con il tuo provider.

D: Dove devo inserire l'header con la mia API key o la query string?

Preferisci un header (es. X-API-Key). Usa la chiave nella query string solo se il provider lo richiede esplicitamente.

D: Perché ricevo errori 401/403?

Credenziali non valide o mancanti, tipo di autenticazione errato, token scaduto o scope/permessi insufficienti. Ricontrolla l'Autorizzazione e gli header obbligatori.

D: Il provider dice che il mio JSON non è valido (400/422). Cosa devo verificare?

Verifica Content-Type, campi obbligatori, tipi di dato e struttura annidata. Confronta con lo schema del provider o esegui un test con Postman.

D: Posso includere array o oggetti annidati nel payload?

Sì. Costruisci JSON annidato o array e mappa i valori dinamici dove necessario (vedi gli esempi sopra).

D: Posso acquisire e consultare la risposta?

Se disponibile nel tuo account, abilita Save response from this Webhook e consulta i Log di esecuzione (Execution Logs) del Workflow e i log del provider.

D: Come scelgo tra Custom Webhook e Webhook (Outbound)?

Usa il Custom Webhook quando hai bisogno di autenticazione avanzata e costruzione flessibile delle richieste. Usa il Webhook (Outbound) per pattern più semplici e predefiniti.