Utilizzare i webhook con i flussi di lavoro di HubSpot

Utilizzate i webhook nei flussi di lavoro per inviare o recuperare informazioni tra HubSpot e altri strumenti esterni. I webhook possono essere utilizzati in vari modi; tra gli esempi di casi d'uso più diffusi vi sono:

• Inviare i dati di un contatto HubSpot a un altro sistema, ad esempio un CRM, quando quel contatto compila un particolare modulo sul vostro sito.

• Inviare i dati di un affare a un sistema esterno di gestione delle spedizioni per creare un ordine di acquisto.

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

Con i flussi di lavoro è possibile inviare richieste sia POST che GET. HubSpot regola il traffico dei webhook separatamente dagli altri processi di workflow. Questo 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 può richiedere più tempo del previsto.

Nota bene: HubSpot riprova i webhook falliti per un massimo di tre giorni, a partire da un minuto dopo il fallimento. I fallimenti successivi verranno riproposti a intervalli crescenti, con un intervallo massimo di otto ore tra un tentativo e l'altro. I flussi di lavoro non verranno ritentati dopo aver ricevuto codici di stato di risposta della serie 4XX.
Un'eccezione a questa regola è rappresentata dagli errori di limite di velocità 429; i flussi di lavoro eseguono automaticamente un nuovo tentativo dopo aver ricevuto una risposta 429 e rispettano l'intestazione Retry-After se presente. Il Retry-After viene registrato in milisecondi. Per conoscere le eccezioni specifiche ai codici di errore, consultare la documentazione per sviluppatori di HubSpot.

Per saperne di più sui webhook, consultate la documentazione sui webhook per gli sviluppatori. Se avete domande sulla vostra specifica implementazione dei webhook con HubSpot, contattate i forum degli sviluppatori di HubSpot.

Impostare una richiesta POST

• Nel tuo account HubSpot, passa a Automazioni > Flussi di lavoro.
• Per modificare un flusso di lavoro esistente, fare clic sul nome del flusso di lavoro. Oppure, creare un nuovo flusso di lavoro.
• Nell'editor del flusso di lavoro, fare clic sull'icona + più per aggiungere un'azione.
• Nel pannello di sinistra, nella sezione Data ops, selezionare Invia un webhook.
  

• Fare clic sul menu a discesa Metodo e selezionare POST.
• Inserire l'URL del webhook.
  • Gli URL Webhook sono limitati a un protocollo sicuro e devono iniziare con HTTPS.
  • Per richiedere informazioni specifiche, è possibile aggiungere all'URL Webhook parametri di query come ?queryparameter=abc .
  • Se non sono stati aggiunti parametri di query, verrà inviata una richiesta generica POST o GET.
• Impostare il tipo di autenticazione per autenticare le richieste al webhook. Si può usare una firma di richiesta nell'intestazione del webhook o una chiave API:
  • Per utilizzare una firma di richiesta nell'intestazione del webhook:
    • Fare clic sul menu a discesa Tipo di autenticazione. Quindi, selezionare Includi firma della richiesta nell'intestazione.
    • Quindi, inserire il proprio HubSpot App ID. 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 utilizzata dipendono dalla configurazione del webhook. Per motivi di sicurezza, la chiave API non verrà visualizzata in nessuna richiesta di test. Per utilizzare una chiave API:
      • Fare clic sul menu a discesa Tipo di autenticazione. Selezionare quindi Chiave API.

• • • • Inserire il nome della chiave API.
      • Fare clic sul menu a discesa Posizione della chiave API. Quindi, selezionare Parametri della query o Intestazione della richiesta. Per saperne di più sull'uso delle chiavi API in HubSpot.
    • Se si effettua una richiesta alle API di HubSpot:
      • Fare clic sul menu a discesa Chiave API e selezionare un segreto. Il valore del segreto deve essere nel formato Bearer [YOUR_TOKEN].
      • Impostare il valore del nome della chiave API su Authorization.
      • Impostare il valore di API key location su Request Header.

• Per includere tutte le proprietà, selezionare Includi tutte le proprietà [oggetto].
• Per includere solo proprietà specifiche:
  
  • Selezionare Personalizza corpo della richiesta.
  • Per personalizzare il corpo della richiesta utilizzando una proprietà di HubSpot, inserire la Chiave e selezionare una proprietà. Per aggiungere un'altra proprietà, fare clic su Aggiungi proprietà.
  • Per personalizzare il corpo della richiesta utilizzando un campo statico, inserire la Chiave e il Valore. Per aggiungere un'altra proprietà, fare clic su Aggiungi valore statico.

• • Per rimuovere una proprietà o un valore statico, fare clic sull'icona del cestino delete.
• Fare clic su Salva.

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

Impostare una richiesta GET

• Nel tuo account HubSpot, passa a Automazioni > Flussi di lavoro.
• Per modificare un flusso di lavoro esistente, fare clic sul nome del flusso di lavoro. Oppure, creare un nuovo flusso di lavoro.
• Nell'editor del flusso di lavoro, fare clic sull'icona + più per aggiungere un'azione.
• Nel pannello di sinistra, nella sezione Data ops, selezionare Invia un webhook.
  

• Fare clic sul menu a discesa Metodo e selezionare GET.
• Inserire l'URL del webhook.
  • Gli URL Webhook sono limitati a un protocollo sicuro e devono iniziare con HTTPS.
  • Per richiedere informazioni specifiche, è possibile aggiungere all'URL Webhook parametri di query come ?queryparameter=abc .
  • Se non sono stati aggiunti parametri di query, verrà inviata una richiesta generica POST o GET.
• Impostare il tipo di autenticazione per autenticare le richieste al webhook. Si può usare una firma di richiesta nell'intestazione del webhook o una chiave API:
  • Per utilizzare una firma di richiesta nell'intestazione del webhook:
    • Fare clic sul menu a discesa Tipo di autenticazione. Quindi, selezionare Includi firma della richiesta nell'intestazione.
    • Quindi, inserire il proprio HubSpot App ID. 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 utilizzata dipendono dalla configurazione del webhook. Per motivi di sicurezza, la chiave API non verrà visualizzata in nessuna richiesta di test. Per utilizzare una chiave API:
      • Fare clic sul menu a discesa Tipo di autenticazione. Selezionare quindi Chiave API.

• • • • Inserire il nome della chiave API.
      • Fare clic sul menu a discesa Posizione della chiave API. Quindi, selezionare Parametri della query o Intestazione della richiesta. Per saperne di più sull'uso delle chiavi API in HubSpot.
    • Se si effettua una richiesta alle API di HubSpot:
      • Fare clic sul menu a discesa Chiave API e selezionare un segreto. Il valore del segreto deve essere nel formato Bearer [YOUR_TOKEN].
      • Impostare il valore del nome della chiave API su Authorization.
      • Impostare il valore di API key location su Request Header.

• Per utilizzare una proprietà HubSpot come parametro di query:
  • Nella sezione Parametri di query , inserire la Chiave, quindi selezionare una proprietà.
  • Per aggiungere un'altra proprietà, fare clic su Aggiungi proprietà.
  • Per rimuovere una proprietà, fare clic sull'icona del cestino delete.
• Per usare un valore statico come parametro di query:
  • Nella sezione Parametri di query , inserire la Chiave, quindi inserire un valore.
  • Per aggiungere un'altra proprietà, fare clic su Aggiungi valore statico.
  • Per rimuovere una proprietà, fare clic sull'icona del cestino delete.
• Fare clic su Salva.

Testare il webhook in HubSpot

Quando si imposta il webhook POST o GET, è possibile 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 interessati. Se si utilizza una chiave API per l'autenticazione, la chiave API non verrà visualizzata nelle richieste di test.

Dopo aver testato il webhook, è possibile selezionare i campi da utilizzare come input in un secondo momento nel flusso di lavoro. Selezionare solo gli output disponibili in ogni risposta. Se l'output viene utilizzato in un'azione successiva ma non è disponibile nella risposta, l'azione fallirà.

• Nel tuo account HubSpot, passa a Automazioni > Flussi di lavoro.
• Fare clic sul nome del flusso di lavoro.
• Nell'editor del flusso di lavoro, fare clic sull'azione Invia un webhook.
• Nel pannello di sinistra, fare clic su Azione di test per espandere la sezione.
• Se si sta testando una richiesta POST, fare clic sul menu a discesa [oggetto], quindi selezionare un record da testare.
• Fare clic su Test.
• Per controllare i dettagli del webhook, selezionare la scheda Risposta o Richiesta. In ogni scheda, è possibile fare clic su Apri tutto per espandere tutte le sezioni o su Chiudi tutto per chiudere tutte le sezioni.
  
  • Nella scheda Risposta, fare clic su intestazioni: o corpo: per espandere ogni sezione.
  • Nella scheda Richiesta , fare clic su httpHeaders: per espandere la sezione.
    
    

Testare il webhook esternamente

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

• Nel browser, navigare all'indirizzo https://webhook.site e copiare l'URL univoco.
• Incollare l'URL nel campo URL Webhook dell'azione Webhook.
• Una volta attivato il flusso di lavoro, è possibile iscrivere manualmente un contatto di prova.
  
  

• Quando si testa il webhook all'esterno:
  • 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, compresi gli invii di moduli, le iscrizioni agli elenchi 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 bene: i valori storici delle proprietà saranno restituiti solo nei flussi di lavoro basati sui contatti. I webhook utilizzati in tutti gli altri tipi di workflow restituiranno solo il valore più recente.

Verifica delle firme delle richieste nei webhook dei flussi di lavoro

Se è stata selezionata la firma della richiesta nella sezione Autenticazione per l'azione Trigger a webhook, HubSpot popolerà il webhook con un'intestazione X-HubSpot-Signature con un hash SHA-256 della concatenazione dell'app-secret della vostra applicazione, del metodo HTTP, dell'URI e del corpo non analizzato. Per saperne di più, consultare la documentazione per gli sviluppatori.

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

• Possedere un account di sviluppatore. Se non ne avete uno, registratevi per ottenere un account da sviluppatore.
• Possedere un'app. Se non avete un'app, imparate a crearne una.
• Controllare il valore hash della firma.

Attivare flussi di lavoro da webhooks

I webhook possono essere utilizzati per attivare i flussi di lavoro. Quando i dati cambiano in un'applicazione di terze parti, si può attivare un flusso di lavoro. Per saperne di più sull'attivazione di flussi di lavoro da webhook.

Utilizzare i dati webhook nel pannello dati

I dati del webhook collegato al vostro account possono essere utilizzati per determinate azioni nel pannello dati.

Per utilizzare i dati del webhook collegato:

• Nel tuo account HubSpot, passa a Automazioni > Flussi di lavoro.
• Fare clic sul nome del flusso di lavoro.
• Fare clic sull'icona + più per aggiungere un'azione.
• Nel pannello di sinistra, selezionare un'azione che utilizzi il pannello dei dati.
• Nel pannello dei dati, fare clic sul menu a discesa Visualizza proprietà o output dell'azione e selezionare Attivazione webhook. È quindi possibile utilizzare le proprietà del webhook collegato.