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

INDICE DEI CONTENUTI

Cos'è il Custom Webhook?

Il Custom Webhook è un'azione Workflow in uscita che invia una richiesta HTTP a un URL da te scelto. Quando l'esecuzione di un Workflow raggiunge questo step, HITLEAD assembla header, parametri e payload (compresi i valori dinamici mappati) e invia la richiesta al sistema esterno.

Vantaggi principali del Custom Webhook

Capire quando usare il Custom Webhook ti aiuta a scegliere lo strumento di automazione giusto e a strutturare correttamente le richieste 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, o No auth con header personalizzati.
  • Mappatura precisa dei dati: I valori dinamici (es. {{contact.email}}) popolano header, parametri o body, così ogni chiamata include i dati del record corretto.
  • Pattern riutilizzabili: Configura una volta e riutilizza in più Workflow con header, content type e strutture payload coerenti.
  • Troubleshooting più rapido: La cattura opzionale della risposta e i log di esecuzione del Workflow semplificano i test e la risoluzione dei problemi.

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 i parametri query solo se il provider lo richiede esplicitamente.

    Esempio header:

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

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

  • Basic Auth

    Inserisci Username e Password nei campi Authorization dell'azione. HITLEAD invierà automaticamente il corretto header Authorization: Basic ....

  • OAuth2

    Se il tuo provider usa OAuth2, configura prima il token in Global Workflow Settings → OAuth2 / Manage Tokens, poi selezionalo nell'azione. OAuth2 è consigliato per i provider che ruotano o aggiornano automaticamente i token.

  • No Auth + Header personalizzato

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

Metodi HTTP e componenti della richiesta

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

  • URL e parametri path: Puoi includere variabili nel path, es. https://api.example.com/contacts/{{contact.id}}.
  • GET: Recupera dati. I body vengono generalmente ignorati — usa i parametri query: https://api.example.com/leads?email={{contact.email}}&status=active
  • POST: Crea risorse. Invia un body JSON o dati form (vedi Content-Type).
  • PUT: Aggiorna risorse. Di solito richiede un ID nel path e un body JSON.
  • DELETE: Elimina risorse. Spesso include l'ID nel path.
  • 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 UI)

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

  • Event = CUSTOM (avanzato):

    • Mostra il selettore Method (GET, POST, PUT, DELETE), 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.
    • Usa questa modalità 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 mostrati. Scegli CUSTOM per il controllo completo.

  • Selettore variabili:

    • L'icona a forma di tag accanto ai campi (URL, Headers, Query Params, Body) apre il selettore di valori dinamici per inserire valori come {{contact.id}}.

Header e parametri query

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

  • Esempi di header:

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

  • Esempi di parametri query:

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

  • Evita di inserire segreti nei parametri query, a meno che il 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 dati del Workflow — strutturati per corrispondere all'API esterna.

  • Payload JSON piatto (POST / crea):

    {
  "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 evita automazioni non funzionanti. Usa sia gli strumenti lato provider che i log del Workflow.

  • Usa Test Workflow (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.
  • Controlla prima le basi: URL corretto, metodo, Content-Type, header richiesti e credenziali valide.
  • Controlla i Execution Logs / la cronologia delle esecuzioni per confermare che l'azione si sia attivata e rivedere i codici di stato.
  • Se non vedi Content-Type o un editor Raw Body, verifica la selezione di 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 dati corrispondano ai requisiti del provider.
    • 401/403 Non autorizzato/Vietato → correggi token, chiave, scope o permessi dell'account.
    • 404 Path/ID errato → verifica l'endpoint e le variabili nel path.
    • 409 Conflitto/idempotenza → assicurati di usare ID univoci o segui le regole di upsert del provider.
    • 429 Rate limit raggiunto → rallenta le richieste o aggiungi ritardi/retry entro i 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 qui sotto per configurare URL, event/method, autorizzazione, header/parametri e payload correttamente, prima di eseguire i test.

Apri il tuo Workflow

Vai su Automation → Workflows e apri il Workflow in cui vuoi inviare i dati, così l'esecuzione raggiungerà questa azione con il contesto del record corretto.

Schermata 1 — Azione Workflow - Custom Webhook

Aggiungi l'azione

Fai clic su + Add action → Send Data → Custom Webhook per creare lo step che effettuerà la chiamata HTTP in uscita.

Schermata 2 — Azione Workflow - Custom Webhook

Assegna un nome all'azione

Dai all'azione un nome chiaro e descrittivo per semplificare la lettura e il troubleshooting in futuro; ad esempio, Send Lead to External CRM.

Schermata 3 — Azione Workflow - Custom Webhook

Seleziona l'Event (e il Method quando applicabile)

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

Schermata 4 — Azione Workflow - Custom Webhook

Schermata 5 — Azione Workflow - Custom Webhook

Inserisci l'URL

Incolla l'endpoint del tuo provider e includi variabili nel path quando necessario, ad esempio https://api.example.com/leads/{{contact.id}}, così ogni richiesta punta al record corretto.

Schermata 6 — Azione Workflow - Custom Webhook

Scegli l'autorizzazione

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

Schermata 7 — Azione Workflow - Custom Webhook

Aggiungi Header e Query Parameters (se necessario)

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

Schermata 8 — Azione Workflow - Custom Webhook

Schermata 9 — Azione Workflow - Custom Webhook

Salva la risposta del Webhook (opzionale)

Attiva la cattura della risposta se disponibile nel tuo account per facilitare il troubleshooting e la conservazione dei dati.

Schermata 10 — Azione Workflow - Custom Webhook

Salva e testa

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

Domande frequenti

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

No. Puoi usare qualsiasi Trigger. Assicurati che le variabili mappate (es. i campi del contatto) esistano al momento dell'esecuzione.

D: Il mio provider richiede un allowlist di IP statici. HITLEAD può fornirne uno?

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

D: Dove inserisco l'header con la mia API key o il parametro query?

Preferisci un header (es. X-API-Key). Usa i parametri query 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 Authorization e gli header richiesti.

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

Conferma Content-Type, campi obbligatori, tipi di dati 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ì. Crea JSON annidato o array e mappa i valori dinamici dove necessario (vedi esempi sopra).

D: Posso catturare e consultare la risposta?

Se disponibile nel tuo account, attiva Save response from this Webhook e consulta i Execution Logs del Workflow insieme ai log del provider.

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

Usa Custom Webhook quando hai bisogno di autenticazione avanzata e configurazione flessibile della richiesta. Usa Webhook (Outbound) per pattern più semplici e predefiniti.