Hoe je webhooks activeert in contactgebaseerde workflows in HubSpot

Gebruik webhooks in contactgebaseerde workflows om gegevens uit te wisselen tussen HubSpot en je externe tools. Zo kun je processen over verschillende platforms heen automatiseren. Je kunt een POST-webhook gebruiken om gegevens vanuit HubSpot te verzenden, en een GET-webhook om gegevens uit externe tools op te halen.

Bij het instellen van je POST- of GET-webhooks kun je de uitvoersnelheid van de webhooks regelen met rate limits, en je webhookconfiguratie handmatig testen binnen HubSpot of met behulp van externe tools. 
Je kunt ook leren hoe je verzoeken vanuit HubSpot kunt verifiëren, hoe je webhooks kunt gebruiken om workflows automatisch te starten en hoe je responsgegevens van webhooks kunt gebruiken in andere workflowacties.

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

Wat zijn enkele voorbeelden

van

gebruiksscenario’s voor webhooks?

Voorbeelden van veelvoorkomende gebruiksscenario’s voor webhooks zijn onder meer:

• Het doorsturen van HubSpot-contactgegevens naar een ander systeem, zoals een CRM, wanneer dat contact een bepaald formulier op je site invult.

• Dealgegevens verzenden naar een extern verzendingssysteem om een inkooporder aan te maken.

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

Je kunt zowel POST- als GET-verzoeken verzenden via workflows. HubSpot regelt het webhook-verkeer apart van andere workflowprocessen. Dit wordt gedaan om de prestaties van workflows en webhooks te optimaliseren. Wanneer een webhook traag is of een time-out geeft, kan het langer duren dan verwacht voordat de workflowactie wordt uitgevoerd.

Hoe verstuur ik gegevens vanuit HubSpot met behulp van een POST-webhook?

1. Klik in je HubSpot-account op Meer en navigeer vervolgens naar Automatisering > Workflows. Als Meer niet in je account verschijnt, navigeer dan direct naar Automatisering > Workflows.
2. Klik op de naam van de workflow om een bestaande workflow te bewerken. Of maak een nieuwe workflow aan.
3. Klik in de workflow-editor op het plusteken (+) om een actie toe te voegen.
4. Selecteer in het linkerpaneel, in het gedeelte Data ops, de optie Een webhook verzenden.
    

5. Klik op het vervolgkeuzemenu 'Methode ' en selecteer 'POST'.
6. 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 aan de webhook-URL toevoegen .
   • Als er geen queryparameters zijn toegevoegd, wordt een generiek POST- of GET-verzoek verzonden.
7. Stel uw authenticatietype in om verzoeken aan uw webhook te authenticeren. U kunt ofwel een verzoekhandtekening in uw webhook-header gebruiken, ofwel een API-sleutel:
   • Om een verzoekhandtekening in de header van uw webhook te gebruiken:
     • Klik op het vervolgkeuzemenu 'Authenticatietype '. Selecteer vervolgens 'Verzoekhandtekening opnemen in header'.
     • Voer vervolgens je HubSpot-app-ID in. Lees hier hoe je verzoekhandtekeningen kunt verifiëren.
   • Om een API-sleutel of een openbare app die via een ontwikkelaarsaccount is aangemaakt te gebruiken voor authenticatie:
     • Wanneer je een API-sleutel gebruikt voor authenticatie, zijn de naam en de locatie van de API-sleutel 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 vervolgkeuzemenu 'Authenticatietype '. Selecteer vervolgens 'API-sleutel'.
       • Voer de naam van je API-sleutel in.
       • Klik op het vervolgkeuzemenu 'API-sleutellocatie '. Selecteer vervolgens 'Queryparameters ' of 'Verzoekheader'. Lees meer over het gebruik van API-sleutels in HubSpot.
     • Als je een verzoek indient bij HubSpot-API's:
       • Klik op het vervolgkeuzemenu 'API-sleutel' en selecteer een geheim. De waarde van het geheim moet de volgende indeling hebben: Bearer [YOUR_TOKEN].
       • Stel de waarde van 'API-sleutelnaam' in op 'Authorization'.
       • Stel de waarde van 'API-sleutellocatie' in op 'Verzoekheader'.
8. Om alle eigenschappen op te nemen, selecteert u 'Alle [object]-eigenschappen opnemen'.
9. Om alleen specifieke eigenschappen op te nemen:
   • Selecteer 'Verzoektekst aanpassen'.
   • Om de verzoektekst aan te passen met behulp van een HubSpot-eigenschap, voer je de sleutel in en selecteer je een eigenschap. Om nog een eigenschap toe te voegen, klik je op 'Eigenschap toevoegen'.
   • Om de verzoektekst aan te passen met behulp van een statisch veld, voer je de sleutel en de waarde in. Om nog een eigenschap toe te voegen, klik je op 'Statische waarde toevoegen'.
   • Om een eigenschap of statische waarde te verwijderen, klik je op het prullenbakpictogram.
10. Klik bovenaan op 'Opslaan'.

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

Hoe haal ik gegevens op in HubSpot met behulp van een GET-webhook?

1. Klik in je HubSpot-account op Meer en navigeer vervolgens naar Automatisering > Workflows. Als Meer niet in je account verschijnt, navigeer dan direct naar Automatisering > Workflows.
2. Klik op de naam van de workflow om een bestaande workflow te bewerken. Of maak een nieuwe workflow aan.
3. Klik in de workflow-editor op het plusteken (+) om een actie toe te voegen.
4. Selecteer in het linkerpaneel, in het gedeelte Data ops, de optie Een webhook verzenden.
    

5. Klik op het vervolgkeuzemenu 'Methode ' en selecteer 'GET'.
6. 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 aan de webhook-URL toevoegen .
   • Als er geen queryparameters zijn toegevoegd, wordt een generiek POST- of GET-verzoek verzonden.
7. Stel uw authenticatietype in om verzoeken aan uw webhook te authenticeren. U kunt ofwel een verzoekhandtekening in uw webhook-header gebruiken, ofwel een API-sleutel:
   • Om een verzoekhandtekening in de header van uw webhook te gebruiken:
     • Klik op het vervolgkeuzemenu 'Authenticatietype '. Selecteer vervolgens 'Verzoekhandtekening opnemen in header'.
     • Voer vervolgens je HubSpot-app-ID in. Lees hier hoe je verzoekhandtekeningen kunt verifiëren.
   • Om een API-sleutel of een openbare app die via een ontwikkelaarsaccount is aangemaakt te gebruiken voor authenticatie:
     • Wanneer je een API-sleutel gebruikt voor authenticatie, zijn de naam en de locatie van de API-sleutel 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 vervolgkeuzemenu 'Authenticatietype '. Selecteer vervolgens 'API-sleutel'.
       • Voer de naam van je API-sleutel in.
       • Klik op het vervolgkeuzemenu 'API-sleutellocatie '. Selecteer vervolgens 'Queryparameters ' of 'Verzoekheader'. Lees meer over het gebruik van API-sleutels in HubSpot.
     • Als je een verzoek indient bij HubSpot-API's:
       • Klik op het vervolgkeuzemenu 'API-sleutel' en selecteer een geheim. De waarde van het geheim moet de volgende indeling hebben: Bearer [YOUR_TOKEN].
       • Stel de waarde van 'API-sleutelnaam' in op 'Authorization'.
       • Stel de waarde van 'API-sleutellocatie' in op 'Verzoekheader'.
8. Als je een GET-verzoek instelt, kun je gebruikmaken van HubSpot-eigenschappen of statische waarden toevoegen als queryparameters: 

9. Om een HubSpot-eigenschap als queryparameter te gebruiken:
   • Voer in het gedeelte Queryparameters de sleutel in en selecteer vervolgens een eigenschap.
   • Om nog een eigenschap toe te voegen, klik je op 'Eigenschap toevoegen'.
   • Klik op het verwijderpictogram om een eigenschap te verwijderen.
10. Om een statische waarde als queryparameter te gebruiken:
    • Voer in het gedeelte 'Queryparameters' de sleutel in en voer vervolgens een waarde in.
    • Om een andere eigenschap toe te voegen, klikt u op 'Statische waarde toevoegen'.
    • Om een eigenschap te verwijderen, klikt u op het verwijderpictogram.
11. Klik op 'Opslaan'.

Hoe regel ik de uitvoersnelheid van een webhook met behulp van snelheidslimieten?

Stel een snelheidslimiet in om te bepalen hoe snel de webhook-actie moet worden uitgevoerd. De snelheidslimiet heeft ook invloed op alle volgende acties in de workflow.

1. Klik in je HubSpot-account op Meer en navigeer vervolgens naar Automatisering > Workflows. Als Meer niet in je account verschijnt, navigeer dan direct naar Automatisering > Workflows.
2. Klik op de naam van de workflow.
3. Klik in de workflow-editor op de actie ‘Een webhook verzenden ’.
4. Klik in het linkerpaneel op 'Snelheidslimiet configureren' om het gedeelte uit te vouwen.
5. Klik om de schakelaar 'Snelheidsbeperking inschakelen' in te schakelen. Standaard is deze instelling uitgeschakeld. 
6. Stel uw limiet in: 
   • Aantal uitvoeringen: stel het maximale aantal uitvoeringen per tijdsperiodein . 
   • Tijdsbestek: stel het tijdsbestek voor uw snelheidslimiet in. U kunt dit tijdsbestek instellen in seconden, minuten of uren. 

Hoe test ik mijn webhook-configuratie in HubSpot?

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

Nadat je je webhook hebt getest, kun je selecteren welke velden je wilt uitvoeren om deze later in je workflow als invoer te gebruiken. Selecteer alleen uitvoer die in elk antwoord beschikbaar is. Als de uitvoer in een latere actie wordt gebruikt maar niet in het antwoord beschikbaar is, mislukt de actie.

1. Klik in je HubSpot-account op Meer en navigeer vervolgens naar Automatisering > Workflows. Als Meer niet in je account verschijnt, navigeer dan direct naar Automatisering > Workflows.
2. Klik op de naam van de workflow.
3. Klik in de workflow-editor op de actie ‘Een webhook verzenden ’.
4. Klik in het linkerpaneel op 'Actie testen ' om het gedeelte uit te vouwen.
5. Als u een POST-verzoek test, verschilt de configuratie van de webhook-test naargelang u in de webhook-actie hebt gekozen voor 'Verzoektekst aanpassen ' of 'Alle [object]-eigenschappen opnemen '.
   • Als u 'Verzoektekst aanpassen' hebt geselecteerd, voert u de testwaarden voor de eigenschappen in voor uw test.
   • Als u 'Alle [object]-eigenschappen opnemen' hebt geselecteerd, klikt u op het vervolgkeuzemenu [object] en selecteert u vervolgens een record om mee te testen.
6. Klik op Testen.
7. Om de webhook-details te bekijken, selecteert u het tabblad 'Response ' of 'Request '. Op elk tabblad kunt u op 'Open all ' klikken om alle secties uit te vouwen, of op 'Collapse all ' om alle secties samen te vouwen.
   • Klik op het tabblad 'Response' op 'headers:' of 'body:' om de betreffende sectie uit te vouwen.
   • Klik op het tabblad 'Request' op 'httpHeaders:' om de sectie uit te vouwen.
     
     

Hoe test ik webhooks met externe tools?

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

1. Ga in je browser naar https://webhook.site en kopieer de unieke URL.
2. Plak de URL in het veld ‘Webhook-URL’ in je webhook-actie.
3. Zodra je workflow is ingeschakeld, kun je handmatig een testcontact toevoegen.
4. Wanneer u uw webhook extern test:
   • Als een webhook-actie met een POST-verzoek wordt geactiveerd, wordt er een JSON-antwoord naar de webhook verzonden met alle informatie over het contact, inclusief ingevulde formulieren, lidmaatschappen van lijsten en alle waarden van contactkenmerken. Het ontvangende systeem kan vervolgens de JSON-gegevens parseren en deze gebruiken voor zijn eigen toepassing.
   • Als een webhook-actie met een GET-verzoek wordt geactiveerd, wordt een generiek GET-verzoek verzonden, tenzij er aanvullende queryparameters zijn toegepast.

Let op: historische eigenschapswaarden worden alleen geretourneerd in contactgebaseerde workflows. Webhooks die in alle andere workflowtypes worden gebruikt, retourneren alleen de meest recente waarde.

Hoe controleer ik of webhook-verzoeken afkomstig zijn van HubSpot?

Als je in het gedeelte ‘Authenticatie’ voor je actie ‘Een webhook activeren’ de optie ‘Verzoeksignatuur’ hebt geselecteerd, vult HubSpot de webhook aan met een X-HubSpot-Signature-header met een SHA-256-hash van de aaneenschakeling van het app-geheim voor je applicatie, de HTTP-methode, de URI en de niet-geparseerde body. Lees hier meer over in de documentatie voor ontwikkelaars.

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

• Zorg dat je een ontwikkelaarsaccount hebt. Als je er nog geen hebt, meld je dan aan voor een ontwikkelaarsaccount.
• Zorg dat je een app hebt. Als je nog geen app hebt, lees dan hoe je een app kunt maken.
• Controleer de hashwaarde van de handtekening.

Hoe gebruik ik webhooks om workflows automatisch te starten?

Webhooks kunnen worden gebruikt om workflows te activeren. Wanneer gegevens in een app van een derde partij veranderen, kan dit een workflow activeren. Lees meer over het activeren van workflows via webhooks.

Hoe gebruik ik responsgegevens van webhooks in andere workflowacties?

Gegevens van de webhook die aan je account is gekoppeld, kunnen worden gebruikt voor bepaalde acties in het gegevenspaneel.

Om gegevens van de gekoppelde webhook te gebruiken:

1. Klik in je HubSpot-account op Meer en navigeer vervolgens naar Automatisering > Workflows. Als Meer niet in je account verschijnt, navigeer dan direct naar Automatisering > Workflows.
2. Klik op de naam van je workflow.
3. Klik op het plusteken (+) om een actie toe te voegen.
4. Selecteer in het linkerpaneel een actie die gebruikmaakt van het gegevenspaneel.
5. Selecteer in het gegevenspaneel, onder Actiegegevens, de actie ‘Een webhook verzenden ’. Vervolgens kunt u eigenschappen van de gekoppelde webhook gebruiken.
    

Wat gebeurt er als een webhook mislukt?

HubSpot probeert mislukte webhooks maximaal drie dagen lang opnieuw, te beginnen één minuut na de mislukking. Bij volgende mislukkingen worden de pogingen met steeds langere tussenpozen herhaald, met een maximale tussenpoos van acht uur tussen de pogingen.

Workflows voeren geen nieuwe pogingen uit na ontvangst van responsstatuscodes uit de 4XX-reeks. Een uitzondering hierop vormen 429-fouten (rate limit); workflows voeren automatisch een nieuwe poging uit na ontvangst van een 429-respons en houden rekening met de 'Retry-After'-header, indien aanwezig. 'Retry-After' wordt weergegeven in milliseconden. Lees meer over uitzonderingen op specifieke foutcodes in de ontwikkelaarsdocumentatie van HubSpot.