Webhooks triggeren in HubSpot op contact gebaseerde workflows

Gebruik webhooks in workflows om informatie tussen HubSpot en andere externe tools te verzenden of op te halen. Er zijn verschillende toepassingen voor webhooks. Voorbeelden van populaire gebruiksscenario's voor webhooks zijn:

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

• Dealgegevens naar een extern verzendsysteem sturen om een inkooporder aan te maken.

• Het ophalen van gegevens uit een ander systeem om uw HubSpot-records bij te werken.

U kunt zowel POST- als GET-verzoeken verzenden met behulp van workflows. HubSpot reguleert webhookverkeer apart van andere workflowprocessen. Dit wordt gedaan om de workflow en webhookprestaties te stroomlijnen. Wanneer een webhook traag is of een time-out heeft, kan het langer duren dan verwacht om de workflowactie uit te voeren.

Let op: HubSpot probeert mislukte webhooks tot drie dagen lang opnieuw, te beginnen één minuut na de mislukking. Daaropvolgende mislukkingen worden met toenemende tussenpozen opnieuw geprobeerd, met een maximale tussenpoos van acht uur tussen de pogingen. Workflows worden niet opnieuw geprobeerd na ontvangst van 4XX-reeksresponsstatuscodes.
Een uitzondering op deze regel zijn 429-fouten met betrekking tot de limiet; workflows worden automatisch opnieuw geprobeerd na ontvangst van een 429-respons en respecteren de Retry-After-header indien aanwezig. Retry-After wordt geregistreerd in milliseconden. Lees meer over specifieke uitzonderingen op foutcodes in de documentatie voor ontwikkelaars van HubSpot.

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

Een POST-verzoek instellen

1. Ga in je HubSpot-account naar Automatisering > Workflows.
2. Om een bestaande workflow te bewerken, klikt u op de naam van de workflow. 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, Send a webhook.
    

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 toevoegen aan de webhook-URL.
   • 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 een verzoekhandtekening in uw webhook-header gebruiken of een API-sleutel:
   • Om een verzoekhandtekening in uw webhook-header te gebruiken:
     • Klik op het vervolgkeuzemenu Authenticatietype. Selecteer vervolgens Verzoekhandtekening opnemen in header.
     • Voer vervolgens uw HubSpot-app-ID in. Lees hoe u verzoekhandtekeningen kunt verifiëren.
   • Om een API-sleutel of een openbare app die via een ontwikkelaarsaccount is gemaakt te gebruiken voor authenticatie:
     • Wanneer u een API-sleutel gebruikt voor authenticatie, zijn de naam en 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 uw API-sleutelnaam in.
       • Klik op het vervolgkeuzemenu API-sleutellocatie. Selecteer vervolgens Queryparameters of Verzoekheader. Meer informatie 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 geheime waarde moet de indeling Bearer [UW_TOKEN] hebben.
       • Stel de waarde van de 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, voert u de sleutel in en selecteert u een eigenschap. Om een andere eigenschap toe te voegen, klikt u op Eigenschap toevoegen.
   • Om de hoofdtekst van het verzoek aan te passen met behulp van een statisch veld, voert u de sleutel en waarde in. Om nog een eigenschap toe te voegen, klikt u op Statische waarde toevoegen.
   • Om een eigenschap of statische waarde te verwijderen, klik je op het prullenbakpictogram.
10. Klik op Opslaan.

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

Een GET-verzoek instellen

1. Ga in je HubSpot-account naar Automatisering > Workflows.
2. Om een bestaande workflow te bewerken, klikt u op de naam van de workflow. 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, Send a webhook.
    

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 toevoegen aan de webhook-URL.
   • 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 een verzoekhandtekening in uw webhook-header gebruiken of een API-sleutel:
   • Om een verzoekhandtekening in uw webhook-header te gebruiken:
     • Klik op het vervolgkeuzemenu Authenticatietype. Selecteer vervolgens Verzoekhandtekening opnemen in header.
     • Voer vervolgens uw HubSpot-app-ID in. Lees hoe u verzoekhandtekeningen kunt verifiëren.
   • Om een API-sleutel of een openbare app die via een ontwikkelaarsaccount is gemaakt te gebruiken voor authenticatie:
     • Wanneer u een API-sleutel gebruikt voor authenticatie, zijn de naam en 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 uw API-sleutelnaam in.
       • Klik op het vervolgkeuzemenu API-sleutellocatie. Selecteer vervolgens Queryparameters of Verzoekheader. Meer informatie 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 geheime waarde moet de indeling Bearer [UW_TOKEN] hebben.
       • Stel de waarde van de API-sleutelnaam in op Authorization.
       • Stel de waarde van API-sleutellocatie in op Verzoekheader.
8. Als u een GET-verzoek instelt, kunt u HubSpot-eigenschappen gebruiken 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 een andere eigenschap toe te voegen, klikt u op Eigenschap toevoegen.
   • Om een eigenschap te verwijderen, klikt u op het pictogram 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 pictogram Verwijderen.
11. Klik op Opslaan.

Stel een snelheidslimiet in voor uw webhook

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. Ga in je HubSpot-account 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 configurerenom het gedeelte uit te vouwen.
5. Klik om de schakelaar Snelheidslimiet inschakelen in te schakelen. Deze instelling is standaard uitgeschakeld. 
6. Stel uw snelheidslimiet in: 
   • Actie-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. 

Test uw webhook binnen HubSpot

Wanneer u uw POST- of GET-webhook instelt, kunt u een test uitvoeren om de webhook-respons te bekijken. Tijdens de test worden gegevens verzonden naar en opgehaald van een derde partij, maar dit heeft geen invloed op bestaande records in HubSpot. Als u 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 later in je workflow als invoer te gebruiken. Selecteer alleen uitvoer die in elke respons beschikbaar is. Als de uitvoer in een latere actie wordt gebruikt, maar niet beschikbaar is in de respons, mislukt de actie.

1. Ga in je HubSpot-account 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 het instellen van de webhook-test naargelang u hebt gekozen voor Verzoektekst aanpassen of Alle [object] eigenschappen opnemen in de webhook-actie.
   • Als u Verzoektekst aanpassen hebt geselecteerd, voert u de testwaarden voor uw test in.
   • Als u Alle [object] eigenschappen opnemen hebt geselecteerd, klikt u op het vervolgkeuzemenu [object] en selecteert u een record om mee te testen.
6. Klik op Testen.
7. Om de webhook-details te controleren, 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 in het tabblad Respons op headers: of body: om elke sectie uit te vouwen.
   • Klik in het tabblad Verzoek 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:

1. Ga in uw browser naar https://webhook.site en kopieer de unieke URL.
2. Plak de URL in het veld Webhook-URL in uw webhook-actie.
3. Zodra uw workflow is ingeschakeld, kunt u handmatig een testcontactpersoon registreren.
   
   

4. Wanneer u uw webhook extern test:
   • Als een webhook-actie met een POST-verzoek wordt geactiveerd, wordt een JSON-responsbody naar de webhook gestuurd met alle informatie over het contact, inclusief formulierinzendingen, lijstitel lidmaatschappen en alle contacteigenschapswaarden. Het ontvangende systeem kan vervolgens de JSON-gegevens parseren en 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 op contacten gebaseerde workflows. Webhooks die in alle andere workflowtypes worden gebruikt, retourneren alleen de meest recente waarde.

Verifieer verzoekhandtekeningen in workflow-webhooks

Als je Verzoekhandtekening hebt geselecteerd in het gedeelte Authenticatie voor je Trigger een webhook-actie, vult HubSpot de webhook 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 ongeparseerde body. Lees hier meer over in de documentatie voor ontwikkelaars.

Om te controleren of de verzoeken die op uw 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 u een app hebt. Als u geen app hebt, lees dan hoe u een app kunt maken.
• Controleer de hashwaarde van de handtekening.

Workflows activeren vanuit webhooks

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 vanuit webhooks.

Webhookgegevens gebruiken in het gegevenspaneel

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

Om gegevens uit de gekoppelde webhook te gebruiken:

1. Ga in je HubSpot-account naar Automatisering > Workflows.
2. Klik op de naam van uw 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. Klik in het gegevenspaneel op het vervolgkeuzemenu Eigenschappen of actie-uitvoer weergeven en selecteer Webhook-trigger. U kunt dan eigenschappen van de gekoppelde webhook gebruiken.