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

Utilizza i webhook nei flussi di lavoro per inviare o recuperare informazioni tra HubSpot e altri strumenti esterni. Esistono diversi utilizzi dei webhook. Ecco alcuni esempi di casi d'uso comuni dei webhook:

• Pubblicare i dati di contatto HubSpot su un altro sistema, come un CRM, quando quel contatto compila un determinato modulo sul tuo sito.

• Invio dei dati relativi a una transazione 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.

Puoi inviare richieste POST e GET utilizzando i flussi di lavoro. HubSpot regola il traffico dei webhook separatamente dagli altri processi del flusso di lavoro. Questo viene fatto per ottimizzare le prestazioni del flusso 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.

Nota: HubSpot riproverà i webhook non riusciti per un massimo di tre giorni, a partire da un minuto dopo l'errore. I tentativi successivi verranno ripetuti a intervalli crescenti, con un intervallo massimo di otto ore tra un tentativo e l'altro. I flussi di lavoro non ripeteranno il tentativo dopo aver ricevuto codici di stato di risposta della serie 4XX.
Un'eccezione a questa regola è rappresentata dagli errori di limite di frequenza 429; i flussi di lavoro ripeteranno automaticamente il tentativo dopo aver ricevuto una risposta 429 e rispetteranno l'intestazione Retry-After, se presente. Retry-After viene registrato in millisecondi. Scopri le eccezioni specifiche relative ai codici di errore nella documentazione per sviluppatori di HubSpot.

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

Configura una richiesta POST

1. Nel tuo account HubSpot, passa a 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 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 sono limitati a 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 di richiesta nell'intestazione del tuo webhook oppure una chiave API:
   • Per utilizzare una firma di richiesta nell'intestazione del tuo 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 dalla configurazione del webhook. Per motivi di sicurezza, la chiave API non verrà visualizzata in nessuna richiesta di prova. Per utilizzare una chiave API:
       • Clicca sul menu a tendina Tipo di autenticazione. Quindi, seleziona Chiave API.
       • Inserisci il nome della tua chiave API.
       • Clicca sul menu a tendina Posizione chiave API. Quindi, seleziona Parametri di query o Intestazione richiesta. Scopri di più sull'utilizzo delle chiavi API in HubSpot.
     • Se stai effettuando una richiesta alle API HubSpot:
       • Clicca sul menu a tendina Chiave API e seleziona un segreto. Il valore del segreto deve essere nel formato Bearer [TUO_TOKEN].
       • Imposta il valore del nome della chiave API su Autorizzazione.
       • Imposta il valore di Posizione chiave API su Intestazione 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à 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. Clicca su Salva.

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

Configurare una richiesta GET

1. Nel tuo account HubSpot, passa a 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, fai clic sull'icona + per aggiungere un'azione.
4. Nel pannello di sinistra, nella sezione Operazioni 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 sono limitati a 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 di richiesta nell'intestazione del tuo webhook oppure una chiave API:
   • Per utilizzare una firma di richiesta nell'intestazione del tuo 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 dalla configurazione del webhook. Per motivi di sicurezza, la chiave API non verrà visualizzata in nessuna richiesta di prova. Per utilizzare una chiave API:
       • Clicca sul menu a tendina Tipo di autenticazione. Quindi, seleziona Chiave API.
       • Inserisci il nome della tua chiave API.
       • Clicca sul menu a tendina Posizione chiave API. Quindi, seleziona Parametri di query o Intestazione richiesta. Scopri di più sull'utilizzo delle chiavi API in HubSpot.
     • Se stai effettuando una richiesta alle API HubSpot:
       • Clicca sul menu a tendina Chiave API e seleziona un segreto. Il valore del segreto deve essere nel formato Bearer [TUO_TOKEN].
       • Imposta il valore del nome della chiave API su Autorizzazione.
       • Imposta il valore di Posizione chiave API su Intestazione richiesta.
8. Se stai configurando una richiesta GET, puoi utilizzare le proprietà HubSpot o aggiungere valori statici come parametri di query: 

9. Per utilizzare una proprietà 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 Elimina.
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à, clicca su Aggiungi valore statico.
    • Per rimuovere una proprietà, clicca sull 'icona Elimina.
11. Fare clic su Salva.

Imposta un limite di frequenza per il tuo webhook

Imposta un limite di frequenza per determinare la velocità di esecuzione dell'azione webhook. Il limite di frequenza influirà anche su tutte le azioni successive nel flusso di lavoro.

1. Nel tuo account HubSpot, passa a Automazione > Flussi di lavoro.
2. Fai clic sul nome del flusso di lavoro.
3. Nell'editor del flusso di lavoro, fai clic sull'azione Invia un webhook.
4. Nel pannello di sinistra, fai clic su Configura limite di frequenzaper espandere la sezione.
5. Fai clic per attivare l'interruttore Attiva limite di frequenza. Per impostazione predefinita, questa opzione è disattivata. 
6. Imposta 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 di tempo in secondi, minuti o ore. 

Prova il tuo webhook all'interno di HubSpot

Quando configuri il tuo webhook POST o GET, puoi eseguire un test per visualizzare la risposta del webhook. Durante il test, mentre i dati vengono inviati e recuperati da una terza parte, i record esistenti in HubSpot non saranno influenzati. Se utilizzi una chiave API per l'autenticazione, la chiave API non verrà visualizzata in nessuna richiesta di test.

Dopo aver testato il tuo webhook, puoi selezionare quali campi visualizzare per utilizzarli come input in un secondo momento nel tuo 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 non andrà a buon fine.

1. Nel tuo account HubSpot, passa a 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 Prova 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 Personalizzare il corpo della richiesta o di Includere tutte le proprietà [oggetto] nell'azione webhook.
   • Se hai selezionato Personalizza corpo della richiesta, inserisci i valori di prova 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. Fai clic su Test.
7. Per controllare i dettagli del webhook, seleziona la scheda Risposta o Richiesta. In ciascuna scheda, puoi fare clic su Apri tutto per espandere tutte le sezioni o su Comprimi tutto per comprimere tutte le sezioni.
   • Nella scheda Risposta, fai clic su intestazioni: o corpo: per espandere ciascuna sezione.
   • Nella scheda Richiesta , fai clic su httpHeaders: per espandere la sezione.
     
     

Prova il tuo webhook esternamente

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

1. Nel browser, vai su https://webhook.site e copia l'URL univoco.
2. Incolla l'URL nel campo URL webhook dell'azione webhook.
3. Una volta attivato il flusso di lavoro, puoi registrare manualmente un contatto di prova.
   
   

4. Quando si testa il 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 sul contatto, inclusi i moduli inviati, le iscrizioni alle liste e tutti i valori delle proprietà del contatto. Il sistema ricevente può 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.

Verifica delle firme delle richieste nei webhook dei flussi di lavoro

Se hai selezionato Richiedi firma nella sezione Autenticazione per l'azione Attiva un webhook, HubSpot popolerà il webhook con un'intestazione X-HubSpot-Signature con un hash SHA-256 della concatenazione dell'app-secret per la tua applicazione, il metodo HTTP, l'URI e il corpo non analizzato. Per saperne di più, consulta la documentazione per gli sviluppatori.

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

• Possiedi un account sviluppatore. Se non ne hai uno, registrati per ottenere un account sviluppatore.
• Possiedi un'app. Se non hai un'app, scopri come crearne una.
• Controlla il valore hash della firma.

Attiva i flussi di lavoro dai webhook

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

Utilizza i dati dei webhook nel pannello dati

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

Per utilizzare i dati provenienti dal webhook collegato:

1. Nel tuo account HubSpot, passa a 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 utilizza il pannello dati.
5. Nel pannello dati, fai clic sul menu a discesa Visualizza proprietà o output dell'azione e seleziona Trigger webhook. A questo punto puoi utilizzare le proprietà del webhook collegato.