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:

• Pubblicare i dati dei contatti di HubSpot in un altro sistema, ad esempio un CRM, quando il contatto compila un determinato modulo sul vostro sito.

• Invio dei dati dell'operazione a un sistema esterno di gestione delle spedizioni per la creazione di un ordine di acquisto.

• Invio di avvisi di chat dal sistema esterno al flusso di chat aziendale per notificare ai dipendenti che si è verificato un evento importante.

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

È possibile inviare richieste sia POST che GET utilizzando i flussi di lavoro. 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. Per informazioni sulle eccezioni specifiche dei 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 un webhook nel flusso di lavoro

• Nel tuo account HubSpot, naviga su Automazione > Flussi di lavoro.
• Fare clic sul nome del flusso di lavoro.
• Fare clic sull'icona + per aggiungere un'azione.
• Nel pannello di destra, selezionare Invia un webhook.
• Fare clic sul menu a discesa Metodo, quindi selezionare POST o GET.
• Immettere 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 quali ?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:
  • 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.
    • Inserire quindi il proprio HubSpot App ID. Per sapere come verificare le firme delle richieste.

• • Per l'autenticazione si può anche utilizzare una chiave API o un'app pubblica creata tramite un account di sviluppatore.

Attenzione: a partire dal 30 novembre 2022, le chiavi API di HubSpot sono state deprecate e non sono più supportate. È ancora possibile utilizzare chiavi API esterne per l'autenticazione nei flussi di lavoro HubSpot.

• • • 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. Ulteriori informazioni sull'uso delle chiavi API in HubSpot.
    • Se state facendo una richiesta a una delle nostre API HubSpot:
      • Fare clic sul menu a discesa della 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.
• Se si imposta una richiesta POST, si può scegliere di includere tutte le proprietà del record CRM o di inviare solo proprietà specifiche:
  • Per includere tutte le proprietà, nella sezione Personalizza corpo della richiesta, selezionare Includi tutte le proprietà.
  • Per includere solo proprietà specifiche:
    
    • Nella sezione Personalizza corpo della richiesta, selezionare Scegli proprietà specifiche.
    • Fare clic sul menu a discesa Scegli proprietà. Quindi, fare clic su [oggetto] in questo flusso di lavoro e selezionare una proprietà.
    • Per modificare il nome di una proprietà nel webhook, modificare il campo di testo Nome proprietà . Questa operazione aggiornerà solo il nome della proprietà nella richiesta POST, ma non il nome della proprietà o il nome interno in HubSpot.
    • Per aggiungere un'altra proprietà, fare clic su Aggiungi proprietà.
    • Per rimuovere una proprietà, fare clic sull'icona del cestino delete.
      

• Se si imposta una richiesta GET, si possono usare le proprietà come parametri di query:
  
  • Nella sezione Parametri di query , fare clic sul menu a discesa Scegli proprietà. Quindi, fare clic su [oggetto] in questo flusso di lavoro e selezionare una proprietà.
  • Per modificare il nome di una proprietà nel parametro di query, modificare il campo di testo Nome proprietà . Questa operazione aggiornerà solo il nome della proprietà nella richiesta GET, ma non il nome della proprietà o il nome interno in HubSpot.
• • Per aggiungere un'altra proprietà, fare clic su Aggiungi parametro query.
  • Per rimuovere una proprietà, 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.

Personalizzare la richiesta POST

Se si imposta una richiesta POST, si può scegliere di includere tutte le proprietà del record CRM o di inviare solo proprietà specifiche:

• Per includere tutte le proprietà, nella sezione Personalizza corpo della richiesta, selezionare Includi tutte le proprietà.
• Per includere solo proprietà specifiche:
  
  • Nella sezione Corpo della richiesta, selezionare Personalizza corpo della richiesta.
  • Inserire la Chiave e il Valore.
  • Per modificare il nome di una proprietà nel webhook, modificare il campo di testo Chiave . Questo aggiornerà solo il nome della proprietà nella richiesta POST, ma non il nome della proprietà o il nome interno in HubSpot.
  • Per aggiungere un'altra proprietà, fare clic su Aggiungi proprietà.
  • Per rimuovere una proprietà, fare clic sull'icona del cestino delete.
    
    

Personalizzare le richieste GET

Se si imposta una richiesta GET, si possono usare le proprietà come parametri di query per recuperare dati specifici:

• Nella sezione Parametri della query , inserire la Chiave, quindi selezionare una proprietà.
• Per modificare il nome di una proprietà nel parametro della query, modificare il campo di testo Nome proprietà . Questa operazione aggiornerà solo il nome della proprietà nella richiesta GET, ma non il nome della proprietà o il nome interno in HubSpot.
• Per aggiungere un'altra proprietà, fare clic su Aggiungi proprietà.
• Per rimuovere una proprietà, fare clic sull'icona del cestino delete.
• Selezionare un tipo di autenticazione dal menu a discesa.
• Fare clic su Salva.
  
  

Testate il vostro 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 pannello laterale, fare clic su Azione di prova per espandere la sezione.
• Fare clic sul menu a discesa Oggetto, quindi selezionare un record con cui eseguire il test.
• Fare clic su Test.
• Per controllare i dettagli del webhook, selezionare la scheda Risposta o Richiesta. In ciascuna 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.
    
    

Testate il vostro webhook esternamente

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

• Nel browser, navigare su https://webhook.site e copiare l'URL univoco.
• Nel campo URL Webhook dell'azione Webhook, incollare l'URL.

• Una volta attivato il flusso di lavoro, è possibile iscrivere manualmente un contatto di prova.

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 del flusso di lavoro

Se avete selezionato Request signature nella sezione Authentication per la vostra azione Trigger a webhook, HubSpot popolerà il webhook con un'intestazione X-HubSpot-Signature con un hash SHA-256 della concatenazione dell'app-secret per la vostra applicazione, il metodo HTTP, l'URI e il 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 per sviluppatori. 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.