Webhooks gebruiken met HubSpot workflows

Gebruik webhooks in workflows om informatie te verzenden of op te halen tussen HubSpot en andere externe tools. Er zijn verschillende toepassingen voor webhooks, voorbeelden van populaire use cases voor webhooks zijn:

• Het posten van HubSpot-contactgegevens naar een ander systeem, zoals een CRM, wanneer die contactpersoon een bepaald formulier op uw site invult.

• Het versturen van dealgegevens naar een extern verzendsysteem om een inkooporder aan te maken.

• Chatwaarschuwingen van uw externe systeem naar de chatstream van uw bedrijf sturen om medewerkers te laten weten dat er iets belangrijks is gebeurd.

• Gegevens ophalen uit een ander systeem om je HubSpot records bij te werken.

Je kunt zowel POST- als GET-verzoeken versturen met behulp van workflows. HubSpot regelt het webhook verkeer apart van andere workflow processen. Dit is gedaan om workflow en webhook prestaties te stroomlijnen. Wanneer een webhook traag is of uitvalt, kan het langer dan verwacht duren voordat de workflow actie wordt uitgevoerd.

Let op: HubSpot zal mislukte webhooks tot drie dagen lang opnieuw proberen, vanaf één minuut na de mislukking. Latere mislukkingen worden met toenemende intervallen opnieuw geprobeerd, met een maximum van acht uur tussen de pogingen. Lees meer over specifieke foutcode uitzonderingen in HubSpot's developer documentatie.

Leer meer over webhooks in de webhooks documentatie voor ontwikkelaars. Als je vragen hebt over jouw specifieke implementatie van webhooks met HubSpot, neem dan contact op met de HubSpot Developers Forums.

Stel een webhook in uw workflow in

• Navigeer in uw HubSpot account naar Automatisering > Workflows.
• Klik op de naam van de workflow.
• Klik op het + pictogram om een actie toe te voegen.
• Selecteer in het rechterpaneel Send a webhook.
• Klik op het keuzemenu Methode en kies POST of GET.
• Voer de webhook-URL in. Webhook URL's zijn beperkt tot een beveiligd protocol en moeten beginnen met HTTPS. Om specifieke informatie op te vragen, kunt u queryparameters zoals ?queryparameter=abc toevoegen aan de Webhook URL. Als er geen queryparameters zijn toegevoegd, wordt een algemeen POST- of GET-verzoek verzonden.
• Stel uw authenticatietype in om verzoeken naar uw webhook te authenticeren:
  • Om een verzoekhandtekening in uw webhook-header te gebruiken:
    • Klik op het keuzemenu Authenticatietype. Selecteer vervolgens Include request signature in header.
    • Voer vervolgens uw HubSpot App ID in. Leer hoe u verzoekhandtekeningen kunt verifiëren.

• • U kunt ook een API-sleutel of een openbare app gemaakt via een ontwikkelaarsaccount gebruiken voor authenticatie.

Let op: vanaf 30 november 2022 worden HubSpot API Keys afgeschreven en niet langer ondersteund. U kunt nog steeds externe API-sleutels gebruiken voor authenticatie in HubSpot-workflows.

• • • Bij gebruik van een API-sleutel voor authenticatie zijn de gebruikte API-sleutelnaam en API-sleutellocatie afhankelijk van hoe de webhook is geconfigureerd. Om veiligheidsredenen wordt de API-sleutel niet weergegeven in testverzoeken. Om een API-sleutel te gebruiken:
      • Klik op het keuzemenu Authenticatietype. Selecteer vervolgens API-sleutel.

• • • • Voer uw API-sleutelnaam in.
      • Klik op het dropdownmenu voor de locatie van de API-sleutel. Selecteer vervolgens Query parameters of Request header. Meer informatie over het gebruik van API-sleutels in HubSpot.
    • Als u een verzoek indient bij een van onze HubSpot API's:
      • Klik op het API-sleutel dropdown menu en selecteer een geheim. De geheime waarde moet in het formaat Bearer [YOUR_TOKEN] zijn.
      • Stel de waarde van API-sleutelnaam in op Autorisatie.
      • Stel de waarde van API key location in op Request Header.
• Als u een POST-verzoek instelt, kunt u ervoor kiezen alle eigenschappen van het CRM-record op te nemen of alleen specifieke eigenschappen te verzenden:
  • Om alle eigenschappen op te nemen, selecteert u in de sectie Request body aanpassen alle eigenschappen opnemen.
  • Als u alleen specifieke eigenschappen wilt opnemen:
    
    • Selecteer in de sectie Request body aanpassen de optie Kies specifieke eigenschappen.
    • Klik op het keuzemenu Kies eigenschap. Klik vervolgens op [object] in deze workflow en selecteer een eigenschap.
    • Om de naam van een eigenschap in de webhook te wijzigen, bewerkt u het tekstveld Eigendomsnaam . Dit zal alleen de eigenschapsnaam in het POST-verzoek bijwerken, het zal de eigenschapsnaam of interne naam in HubSpot niet bijwerken.
    • Om nog een eigenschap toe te voegen, klik je op Eigenschap toevoegen.
    • Om een eigenschap te verwijderen, klikt u op het pictogram delete prullenbak.
      

• Als u een GET verzoek instelt, kunt u eigenschappen gebruiken als query parameters:
  
  • Klik in de sectie Query parameters op het keuzemenu Kies eigenschap. Klik vervolgens op [object] in deze workflow en selecteer een eigenschap.
  • Om de naam van een eigenschap in de queryparameter te wijzigen, bewerkt u het tekstveld Eigendomsnaam . Dit zal alleen de property naam in het GET verzoek bijwerken, het zal de property naam of interne naam in HubSpot niet bijwerken.
• • Om nog een eigenschap toe te voegen, klikt u op Queryparameter toevoegen.
  • Om een eigenschap te verwijderen, klikt u op het delete prullenbak icoon.
• Klik op Opslaan.
  
  

Let op: om meerdere uitgangen te selecteren, moet het antwoord gestructureerd zijn als een JSON-object.

Uw POST-verzoek aanpassen

Als u een POST-verzoek instelt, kunt u ervoor kiezen alle eigenschappen van het CRM-record op te nemen of alleen specifieke eigenschappen te verzenden:

• Om alle eigenschappen op te nemen, selecteert u in de sectie Aanpassen van de verzoektekst de optie Alle eigenschappen opnemen.
• Om alleen specifieke eigenschappen op te nemen:
  
  • Selecteer in de sectie Request body de optie Customize request body.
  • Voer de Sleutel en de Waarde in.
  • Om de naam van een eigenschap in de webhook te wijzigen, bewerkt u het tekstveld Sleutel . Dit zal alleen de naam van de eigenschap in het POST-verzoek bijwerken, het zal de naam van de eigenschap of de interne naam in HubSpot niet bijwerken.
  • Om nog een eigenschap toe te voegen, klik je op Eigenschap toevoegen.
  • Om een eigenschap te verwijderen, klikt u op het pictogram delete prullenbak.
    
    

Uw GET-verzoeken aanpassen

Als u een GET verzoek instelt, kunt u eigenschappen gebruiken als query parameters om specifieke gegevens op te halen:

• In de sectie Query parameters voert u de Sleutel in en selecteert u vervolgens een eigenschap.
• Om de naam van een eigenschap in de query parameter te wijzigen, bewerk je het Property name tekstveld. Dit zal alleen de property naam in het GET verzoek bijwerken, het zal de property naam of interne naam in HubSpot niet bijwerken.
• Om nog een eigenschap toe te voegen klikt u op eigenschap toevoegen.
• Om een eigenschap te verwijderen, klikt u op het delete prullenbak icoon.
• Selecteer een authenticatietype uit het dropdown menu.
• Klik op Opslaan.
  
  

Test uw webhook binnen HubSpot

Bij het opzetten van je POST of GET webhook, kun je een test uitvoeren om de webhook respons te bekijken. Tijdens de test, terwijl gegevens worden verzonden naar en opgehaald van een derde partij, worden bestaande records in HubSpot niet beïnvloed. Als je een API-sleutel gebruikt voor authenticatie, zal de API-sleutel niet worden weergegeven in testverzoeken.

Na het testen van uw webhook, kunt u selecteren welke velden u wilt uitvoeren om later in uw workflow als invoer te gebruiken. Selecteer alleen uitgangen die beschikbaar zijn in elke respons. Als de uitvoer wordt gebruikt in een latere actie, maar niet beschikbaar is in de respons, zal de actie mislukken.

• Klik in het zijpaneel op Testactie om de sectie uit te breiden.
• Klik op het Object dropdown menu en kies een Record om mee te testen.
• Klik op Test.
• Om de details van de webhook te controleren, selecteert u het tabblad Antwoord of Verzoek. Op elk tabblad kunt u klikken op Alles openen om alle secties uit te vouwen, of Alles samenvouwen om alle secties samen te vouwen.
  
  • Op het tabblad Reactie klikt u op headers: of body: om elke sectie uit te vouwen.
  • Op het tabblad Request klikt u op httpHeaders: om de sectie uit te vouwen.
    
    

Test uw webhook extern

Nadat u uw workflow met een webhook actie hebt gemaakt, kunt u een snelle test uitvoeren met een dummy webhook URL:

• Navigeer in uw browser naar https://webhook.site en kopieer de unieke URL.
• Plak de URL in het veld Webhook URL in uw webhook-actie.

• Zodra uw workflow is ingeschakeld, kunt u handmatig een testcontact inschrijven.

Als een webhook actie met een POST verzoek wordt getriggerd, wordt een JSON respons body naar de webhook gestuurd die alle informatie over de contactpersoon bevat, inclusief formulierinzendingen, lijstlidmaatschappen, en alle contacteigenschap waarden. Het ontvangende systeem kan dan de JSON-gegevens ontleden en gebruiken voor zijn eigen toepassing.

Als een webhook-actie met een GET-verzoek wordt geactiveerd, wordt een generiek GET-verzoek verzonden, tenzij aanvullende query-parameters zijn toegepast.

Let op: historische waarden van eigenschappen worden alleen geretourneerd in contactgebaseerde workflows. Webhooks die in alle andere workflowtypes worden gebruikt, geven alleen de meest recente waarde terug.

Controleer verzoekhandtekeningen in workflow webhooks

Wanneer je Request signature hebt geselecteerd in de Authentication sectie voor je Trigger a webhook actie, zal HubSpot de webhook vullen met een X-HubSpot-Signature header met een SHA-256 hash van de aaneenschakeling van de app-secret voor je applicatie, de HTTP-methode, de URI, en de unparsed body. Lees meer hierover in de documentatie voor ontwikkelaars.

Om te controleren of de verzoeken die op uw URL worden ontvangen van HubSpot zijn:

• Bezit een ontwikkelaarsaccount. Als je er geen hebt, meld je dan aan voor een ontwikkelaarsaccount.
• Bezit een app. Als je geen app hebt, leer dan hoe je een app maakt.
• Controleer de hashwaarde van de handtekening.