Come attivare i webhook nei flussi di lavoro basati sui contatti di HubSpot

Utilizza i webhook nei flussi di lavoro basati sui contatti per inviare o recuperare dati tra HubSpot e i tuoi strumenti esterni. Ciò ti consente di automatizzare i processi su diverse piattaforme. Puoi utilizzare un webhook POST per inviare dati da HubSpot e un webhook GET per recuperare dati dagli strumenti esterni.

Durante la configurazione dei tuoi webhook POST o GET, controlla la velocità di esecuzione dei webhook tramite limiti di frequenza e verifica manualmente la configurazione dei webhook all’interno di HubSpot o utilizzando strumenti esterni. 
Puoi anche scoprire come verificare le richieste provenienti da HubSpot, come utilizzare i webhook per avviare automaticamente i flussi di lavoro e come utilizzare i dati di risposta dei webhook in altre azioni dei flussi di lavoro.

Scopri di più sui webhook nella documentazione dedicata agli sviluppatori. Se hai domande sulla tua specifica implementazione dei webhook con HubSpot, contatta i forum degli sviluppatori di HubSpot.

Quali sono alcuni esempi

di casi d’uso dei

webhook?

Tra gli esempi di casi d’uso più comuni dei webhook figurano:

• Inviare i dati dei contatti di HubSpot a un altro sistema, come un CRM, quando quel contatto compila un determinato modulo sul tuo sito.

• L'invio dei dati relativi alle trattative a un sistema esterno di gestione delle spedizioni per creare un ordine di acquisto.

• Recupero di dati da un altro sistema per aggiornare i tuoi record HubSpot.

È possibile inviare sia richieste POST che GET utilizzando i flussi di lavoro. HubSpot gestisce il traffico dei webhook separatamente dagli altri processi dei flussi di lavoro. Ciò viene fatto per ottimizzare le prestazioni dei flussi di lavoro e dei webhook. Quando un webhook è lento o va in timeout, l’esecuzione dell’azione del flusso di lavoro potrebbe richiedere più tempo del previsto.

Come si inviano dati da HubSpot utilizzando un webhook POST?

1. Nel tuo account HubSpot, fai clic su Altro, quindi vai ad Automazione > Flussi di lavoro. Se Altro non compare nel tuo account, vai direttamente ad Automazione > Flussi di lavoro.
2. Per modificare un flusso di lavoro esistente, clicca sul nome del flusso di lavoro. Oppure, crea un nuovo flusso di lavoro.
3. Nell’editor del flusso di lavoro, clicca sull’icona + per aggiungere un’azione.
4. Nel pannello di sinistra, nella sezione Operazioni sui dati, seleziona Invia un webhook.
    

5. Fai clic sul menu a discesa "Metodo " e seleziona " POST".
6. Inserisci l'URL del webhook.
   • Gli URL dei webhook devono utilizzare un protocollo sicuro e devono iniziare con HTTPS.
   • Per richiedere informazioni specifiche, è possibile aggiungere parametri di query come ?queryparameter=abc all'URL del webhook.
   • Se non sono stati aggiunti parametri di query, verrà inviata una richiesta POST o GET generica.
7. Configura il tipo di autenticazione per autenticare le richieste al tuo webhook. Puoi utilizzare una firma della richiesta nell'intestazione del webhook oppure una chiave API:
   • Per utilizzare una firma della richiesta nell'intestazione del webhook:
     • Fai clic sul menu a discesa Tipo di autenticazione. Quindi, seleziona Includi firma della richiesta nell’intestazione.
     • Inserisci quindi il tuo ID app HubSpot. Scopri come verificare le firme delle richieste.
   • Per utilizzare una chiave API o un'app pubblica creata tramite un account sviluppatore per l’autenticazione:
     • Quando si utilizza una chiave API per l’autenticazione, il nome della chiave API e la posizione della chiave API utilizzati dipendono da come è configurato il webhook. Per motivi di sicurezza, la chiave API non verrà visualizzata in nessuna richiesta di test. Per utilizzare una chiave API:
       • Fai clic sul menu a discesa Tipo di autenticazione. Quindi, seleziona Chiave API.
       • Inserisci il nome della tua chiave API.
       • Fai clic sul menu a discesa " Posizione della chiave API ". Quindi, seleziona " Parametri di query " o " Intestazione della richiesta". Scopri di più sull'utilizzo delle chiavi API in HubSpot.
     • Se stai effettuando una richiesta alle API di HubSpot:
       • Fai clic sul menu a discesa " Chiave API " e seleziona un segreto. Il valore del segreto deve essere nel formato Bearer [YOUR_TOKEN].
       • Imposta il valore del nome della chiave API su " Autorizzazione".
       • Imposta il valore di " Posizione della chiave API" su " Intestazione della richiesta".
8. Per includere tutte le proprietà, selezionare " Includi tutte le proprietà [oggetto]".
9. Per includere solo proprietà specifiche:
   • Seleziona " Personalizza corpo della richiesta".
   • Per personalizzare il corpo della richiesta utilizzando una proprietà di HubSpot, inserisci la chiave e seleziona una proprietà. Per aggiungere un'altra proprietà, clicca su "Aggiungi proprietà".
   • Per personalizzare il corpo della richiesta utilizzando un campo statico, inserisci la chiave e il valore. Per aggiungere un'altra proprietà, clicca su " Aggiungi valore statico".
   • Per rimuovere una proprietà o un valore statico, clicca sull'icona del cestino.
10. Nella parte superiore, clicca su " Salva".

Nota: per selezionare più output, la risposta deve essere strutturata come un oggetto JSON.

Come posso recuperare i dati in HubSpot utilizzando un webhook GET?

1. Nel tuo account HubSpot, fai clic su Altro, quindi vai ad Automazione > Flussi di lavoro. Se Altro non compare nel tuo account, vai direttamente ad Automazione > Flussi di lavoro.
2. Per modificare un flusso di lavoro esistente, clicca sul nome del flusso di lavoro. Oppure, crea un nuovo flusso di lavoro.
3. Nell’editor del flusso di lavoro, clicca sull’icona + per aggiungere un’azione.
4. Nel pannello di sinistra, nella sezione Operazioni sui dati, seleziona Invia un webhook.
    

5. Fai clic sul menu a discesa "Metodo " e seleziona GET.
6. Inserisci l'URL del webhook.
   • Gli URL dei webhook devono utilizzare un protocollo sicuro e devono iniziare con HTTPS.
   • Per richiedere informazioni specifiche, è possibile aggiungere parametri di query come ?queryparameter=abc all'URL del webhook.
   • Se non sono stati aggiunti parametri di query, verrà inviata una richiesta POST o GET generica.
7. Configura il tipo di autenticazione per autenticare le richieste al tuo webhook. Puoi utilizzare una firma della richiesta nell'intestazione del webhook oppure una chiave API:
   • Per utilizzare una firma della richiesta nell'intestazione del webhook:
     • Fai clic sul menu a discesa Tipo di autenticazione. Quindi, seleziona Includi firma della richiesta nell’intestazione.
     • Inserisci quindi il tuo ID app HubSpot. Scopri come verificare le firme delle richieste.
   • Per utilizzare una chiave API o un'app pubblica creata tramite un account sviluppatore per l’autenticazione:
     • Quando si utilizza una chiave API per l’autenticazione, il nome della chiave API e la posizione della chiave API utilizzati dipendono da come è configurato il webhook. Per motivi di sicurezza, la chiave API non verrà visualizzata in nessuna richiesta di test. Per utilizzare una chiave API:
       • Fai clic sul menu a discesa Tipo di autenticazione. Quindi, seleziona Chiave API.
       • Inserisci il nome della tua chiave API.
       • Fai clic sul menu a discesa " Posizione della chiave API ". Quindi, seleziona " Parametri di query " o " Intestazione della richiesta". Scopri di più sull'utilizzo delle chiavi API in HubSpot.
     • Se stai effettuando una richiesta alle API di HubSpot:
       • Fai clic sul menu a discesa " Chiave API " e seleziona un segreto. Il valore del segreto deve essere nel formato Bearer [YOUR_TOKEN].
       • Imposta il valore del nome della chiave API su " Autorizzazione".
       • Imposta il valore di " Posizione della chiave API" su " Intestazione della richiesta".
8. Se stai configurando una richiesta GET, puoi utilizzare le proprietà di HubSpot oppure aggiungere valori statici come parametri di query: 

9. Per utilizzare una proprietà di HubSpot come parametro di query:
   • Nella sezione Parametri di query , inserisci la chiave, quindi seleziona una proprietà.
   • Per aggiungere un'altra proprietà, clicca su Aggiungi proprietà.
   • Per rimuovere una proprietà, clicca sull’icona di eliminazione.
10. Per utilizzare un valore statico come parametro di query:
    • Nella sezione Parametri di query , inserisci la chiave, quindi inserisci un valore.
    • Per aggiungere un'altra proprietà, fare clic su " Aggiungi valore statico".
    • Per rimuovere una proprietà, fare clic sull'icona di eliminazione.
11. Fare clic su Salva.

Come posso controllare la velocità di esecuzione dei webhook con i limiti

di frequenza

?

Imposta un limite di frequenza per determinare la velocità con cui deve essere eseguita l'azione del webhook. Il limite di frequenza influirà anche su tutte le azioni successive nel flusso di lavoro.

1. Nel tuo account HubSpot, fai clic su Altro, quindi vai ad Automazione > Flussi di lavoro. Se Altro non compare nel tuo account, vai direttamente ad Automazione > Flussi di lavoro.
2. Fai clic sul nome del flusso di lavoro.
3. Nell'editor del flusso di lavoro, clicca sull'azione Invia un webhook.
4. Nel pannello di sinistra, clicca su " Configura limite di frequenza" per espandere la sezione.
5. Fai clic per attivare l'interruttore "Attiva limitazione di frequenza ". Per impostazione predefinita, questa opzione è disattivata. 
6. Configurare il limite di frequenza: 
   • Esecuzioni dell'azione: imposta il numero massimo di esecuzioni per periodo di tempo. 
   • Intervallo di tempo: imposta l'intervallo di tempo per il limite di frequenza. Puoi impostare questo intervallo in secondi, minuti o ore. 

Come posso testare la configurazione

del mio

webhook in HubSpot?

Durante la configurazione del webhook POST o GET, è possibile eseguire un test per visualizzare la risposta del webhook. Durante il test, mentre i dati vengono inviati a e recuperati da una terza parte, i record esistenti in HubSpot non ne risentiranno. Se si utilizza una chiave API per l’autenticazione, questa non verrà visualizzata in nessuna richiesta di test.

Dopo aver testato il webhook, puoi selezionare quali campi di output utilizzare come input in una fase successiva del flusso di lavoro. Seleziona solo gli output disponibili in ogni risposta. Se l’output viene utilizzato in un’azione successiva ma non è disponibile nella risposta, l’azione fallirà.

1. Nel tuo account HubSpot, fai clic su Altro, quindi vai ad Automazione > Flussi di lavoro. Se Altro non compare nel tuo account, vai direttamente ad Automazione > Flussi di lavoro.
2. Fai clic sul nome del flusso di lavoro.
3. Nell’editor del flusso di lavoro, clicca sull’azione Invia un webhook.
4. Nel pannello di sinistra, fai clic su " Testa azione " per espandere la sezione.
5. Se stai testando una richiesta POST, la configurazione del test del webhook varierà a seconda che tu abbia scelto di " Personalizza il corpo della richiesta " o di " Includi tutte le proprietà [oggetto] " nell'azione webhook.
   • Se hai selezionato " Personalizza corpo della richiesta", inserisci i valori di test delle proprietà per il tuo test.
   • Se hai selezionato " Includi tutte le proprietà [oggetto]", fai clic sul menu a discesa [oggetto], quindi seleziona un record con cui eseguire il test.
6. Fare clic su " Test".
7. Per verificare i dettagli del webhook, seleziona la scheda Risposta o Richiesta. In ciascuna scheda, puoi fare clic su Apri tutto per espandere tutte le sezioni oppure su Comprimi tutto per comprimerle.
   • Nella scheda "Risposta ", fare clic su "intestazioni:" o "corpo:" per espandere ciascuna sezione.
   • Nella scheda "Richiesta ", fai clic su " httpHeaders:" per espandere la sezione.
     
     

Come posso testare i webhook utilizzando strumenti esterni?

Dopo aver creato il flusso di lavoro con un'azione webhook, è possibile eseguire un test rapido con un URL webhook fittizio:

1. Nel browser, vai su https://webhook.site e copia l'URL univoco.
2. Nel campo " URL webhook " dell'azione webhook, incolla l'URL.
3. Una volta attivato il flusso di lavoro, puoi registrare manualmente un contatto di prova.
4. Quando si esegue il test del webhook esternamente:
   • Se viene attivata un'azione webhook con una richiesta POST, al webhook verrà inviato un corpo di risposta JSON contenente tutte le informazioni relative al contatto, inclusi i moduli inviati, le iscrizioni alle liste e tutti i valori delle proprietà del contatto. Il sistema ricevente potrà quindi analizzare i dati JSON e utilizzarli per la propria applicazione.
   • Se viene attivata un'azione webhook con una richiesta GET, verrà inviata una richiesta GET generica, a meno che non siano stati applicati parametri di query aggiuntivi.

Nota: i valori storici delle proprietà verranno restituiti solo nei flussi di lavoro basati sui contatti. I webhook utilizzati in tutti gli altri tipi di flusso di lavoro restituiranno solo il valore più recente.

Come posso verificare che le richieste di webhook provengano da HubSpot?

Se hai selezionato "Firma della richiesta

nella sezione

Autenticazione " per l’azione

Attiva un webhook ", HubSpot inserirà nel webhook un’intestazione X-HubSpot-Signature contenente un hash SHA-256 della concatenazione del segreto dell’app per la tua applicazione, del metodo HTTP, dell’URI e del corpo non analizzato. Per ulteriori informazioni, consulta la documentazione per gli sviluppatori.

Per verificare che le richieste ricevute al tuo URL provengano da HubSpot:

• Disporre di un account sviluppatore. Se non ne possiedi uno, registrati per ottenere un account sviluppatore.
• Possedere un’app. Se non ne possiedi una, scopri come crearne una.
• Controlla il valore dell’hash della firma.

Come si utilizzano i

webhook

per avviare automaticamente

i flussi di

lavoro?

I webhook possono essere utilizzati per attivare i flussi di lavoro. Quando i dati cambiano in un’app di terze parti, ciò può attivare un flusso di lavoro. Scopri di più sull’attivazione dei flussi di lavoro tramite webhook.

Come si utilizzano i dati di risposta dei webhook in altre azioni del flusso di lavoro?

I dati provenienti dal webhook collegato al tuo account possono essere utilizzati per determinate azioni nel pannello dei dati.

Per utilizzare i dati provenienti dal webhook collegato:

1. Nel tuo account HubSpot, fai clic su Altro, quindi vai ad Automazione > Flussi di lavoro. Se Altro non compare nel tuo account, vai direttamente ad Automazione > Flussi di lavoro.
2. Fai clic sul nome del tuo flusso di lavoro.
3. Fai clic sull 'icona + per aggiungere un'azione.
4. Nel pannello di sinistra, seleziona un'azione che utilizzi il pannello dei dati.
5. Nel pannello dati, alla voce Dati dell'azione, seleziona l'azione Invia un webhook. A questo punto potrai utilizzare le proprietà del webhook collegato.
    

Cosa succede quando un webhook fallisce?

HubSpot riproverà a eseguire i webhook falliti per un massimo di tre giorni, a partire da un minuto dopo il fallimento. I fallimenti successivi verranno riprovati a intervalli crescenti, con un intervallo massimo di otto ore tra un tentativo e l’altro.

I flussi di lavoro non effettueranno nuovi tentativi dopo aver ricevuto codici di stato di risposta della serie 4XX. Fanno eccezione gli errori di limite di frequenza 429; in questo caso, i flussi di lavoro riproveranno automaticamente dopo aver ricevuto una risposta 429 e rispetteranno l’intestazione "Retry-After", se presente. Il valore di "Retry-After" è espresso in millisecondi. Scopri le eccezioni relative ai codici di errore specifici nella documentazione per sviluppatori di HubSpot.