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 gebruiksmogelijkheden voor webhooks. Voorbeelden van populaire gebruikssituaties voor webhooks zijn onder andere:

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

• Het versturen van dealgegevens naar een extern verzendsysteem 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 met behulp van workflows. HubSpot regelt webhook verkeer apart van andere workflow processen. Dit wordt gedaan om de prestaties van workflows en webhooks te stroomlijnen. Als een webhook traag is of een time-out heeft, kan het langer duren dan verwacht voordat de workflow actie wordt uitgevoerd.

Let op: HubSpot zal mislukte webhooks tot drie dagen lang opnieuw proberen, beginnend één minuut na de mislukking. Latere mislukkingen worden met toenemende intervallen opnieuw geprobeerd, met een maximum van acht uur tussen de pogingen. Workflows worden niet opnieuw geprobeerd na ontvangst van 4XX-serie responsstatuscodes.
Een uitzondering op deze regel zijn 429 rate limit errors; workflows zullen automatisch opnieuw proberen na ontvangst van een 429 antwoord en zullen de Retry-After header respecteren indien aanwezig. Retry-After wordt geregistreerd in milliseconden. Meer informatie over specifieke foutcode uitzonderingen vind je in de HubSpot documentatie voor ontwikkelaars.

Meer informatie over webhooks in de webhooks documentatie voor ontwikkelaars. 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. Klik op de naam van de workflow om een bestaande workflow te bewerken. Of maak een nieuwe workflow.
3. Klik in de workflow editor op het + plus pictogram om een actie toe te voegen.
4. Selecteer in het linkerpaneel, in de sectie 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 veilig 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.
7. Stel uw verificatietype in om verzoeken naar uw webhook te verifiëren. 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 Include request signature in header.
     • Voer vervolgens je HubSpot App ID in. Leer hoe je verzoekhandtekeningen verifieert.
   • Een API-sleutel of een openbare app die is gemaakt via een ontwikkelaarsaccount gebruiken voor verificatie:
     • Wanneer je een API-sleutel gebruikt voor authenticatie, zijn de API-sleutelnaam en API-sleutellocatie die worden gebruikt afhankelijk van hoe de webhook is geconfigureerd. Om veiligheidsredenen wordt de API-sleutel niet weergegeven in testverzoeken. Een API-sleutel gebruiken:
       • Klik op het vervolgkeuzemenu Authenticatietype. Selecteer vervolgens API-sleutel.
       • Voer de naam van uw API-sleutel in.
       • Klik op het vervolgkeuzemenu API-sleutellocatie. Selecteer vervolgens Query parameters of Request header. 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 in het formaat Bearer [YOUR_TOKEN] zijn.
       • Stel de waarde van API-sleutelnaam in op Autorisatie.
       • Stel de waarde van de locatie van de API-sleutel in op Request Header.
8. Als u alle eigenschappen wilt opnemen, selecteert u Alle [object] eigenschappen opnemen.
9. Om alleen specifieke eigenschappen op te nemen:
   • Selecteer Request body aanpassen.
   • Als je de verzoektekst wilt aanpassen met een HubSpot-eigenschap, voer je de sleutel in en selecteer je een eigenschap. Als u nog een eigenschap wilt toevoegen, klikt u op eigenschap toevoegen.
   • Als u de verzoektekst wilt aanpassen met behulp van een statisch veld, voert u de sleutel en de waarde in. Om nog een eigenschap toe te voegen, klikt u op Statische waarde toevoegen.
   • Om een eigenschap of statische waarde te verwijderen, klikt u op het pictogram delete prullenbak.
10. Klik op Opslaan.

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

Een GET-verzoek instellen

1. Ga in je HubSpot-account naar Automatisering > Workflows.
2. Klik op de naam van de workflow om een bestaande workflow te bewerken. Of maak een nieuwe workflow.
3. Klik in de workflow editor op het + plus pictogram om een actie toe te voegen.
4. Selecteer in het linkerpaneel, in de sectie 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 veilig 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.
7. Stel uw verificatietype in om verzoeken naar uw webhook te verifiëren. 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 Include request signature in header.
     • Voer vervolgens je HubSpot App ID in. Leer hoe je verzoekhandtekeningen verifieert.
   • Een API-sleutel of een openbare app die is gemaakt via een ontwikkelaarsaccount gebruiken voor verificatie:
     • Wanneer je een API-sleutel gebruikt voor authenticatie, zijn de API-sleutelnaam en API-sleutellocatie die worden gebruikt afhankelijk van hoe de webhook is geconfigureerd. Om veiligheidsredenen wordt de API-sleutel niet weergegeven in testverzoeken. Een API-sleutel gebruiken:
       • Klik op het vervolgkeuzemenu Authenticatietype. Selecteer vervolgens API-sleutel.
       • Voer de naam van uw API-sleutel in.
       • Klik op het vervolgkeuzemenu API-sleutellocatie. Selecteer vervolgens Query parameters of Request header. 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 in het formaat Bearer [YOUR_TOKEN] zijn.
       • Stel de waarde van API-sleutelnaam in op Autorisatie.
       • Stel de waarde van de locatie van de API-sleutel in op Request Header.
8. Als je een GET-verzoek instelt, kun je HubSpot-eigenschappen gebruiken of statische waarden als queryparameters toevoegen:

9. Om een HubSpot eigenschap als query parameter te gebruiken:
   • Voer in de sectie Queryparameters de Key in en selecteer vervolgens een eigenschap.
   • Om nog een eigenschap toe te voegen, klik je op eigenschap toevoegen.
   • Om een eigenschap te verwijderen, klik je op het pictogram delete verwijderen.
10. Om een statische waarde als query parameter te gebruiken:
    • Voer in de sectie Queryparameters de sleutel in en voer vervolgens een waarde in.
    • Om nog een eigenschap toe te voegen, klikt u op Statische waarde toevoegen.
    • Om een eigenschap te verwijderen, klikt u op het pictogram delete verwijderen.
11. Klik op Opslaan.

Een snelheidslimiet instellen voor je webhook (BETA)

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 Tarieflimiet configureren om de sectie uit te vouwen.
5. Klik op om de schakelaar Rate limiting inschakelen aan te zetten. Standaard is deze instelling uitgeschakeld.
6. Stel uw snelheidslimiet in:
   • Actieuitvoeringen: stel het maximum aantal uitvoeringen per tijdsperiode in.
   • Tijdsbestek: stel het tijdsbestek voor je snelheidslimiet in. Je kunt dit tijdsbestek instellen op Seconden, Minuten of Uren.

Test je webhook binnen HubSpot

Bij het instellen 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, 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 beschikbaar is in elke respons. Als de uitvoer wordt gebruikt in een latere actie, maar niet beschikbaar is in de respons, zal de actie mislukken.

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 Stuur een webhook.
4. Klik in het linkerpaneel op Test actie om de sectie uit te vouwen.
5. Als u een POST-verzoek test, verschilt het instellen van de webhook-test afhankelijk van of u hebt gekozen voor Request body aanpassen of de optie Alle [object] eigenschappen opnemen in de webhook-actie.
   • Als u Customize request body hebt geselecteerd, voert u de testwaarden voor de eigenschappen 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 details van de webhook te controleren, selecteert u het tabblad Response of Request. 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 Response klikt u op headers: of body: om elke sectie uit te vouwen.
   • Klik op het tabblad Request 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. Navigeer 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 testcontact inschrijven.
   
   

4. Als u uw webhook extern test:
   • Als een webhook-actie met een POST-verzoek wordt geactiveerd, wordt een JSON-responslichaam naar de webhook verzonden met alle informatie over de contactpersoon, inclusief formulierinzendingen, lidmaatschappen van lijsten en alle contacteigenschappenwaarden. 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 queryparameters zijn toegepast.

Let op: historische waarden van eigenschappen worden alleen geretourneerd in contactgebaseerde workflows. Webhooks die worden gebruikt in alle andere workflowtypen zullen alleen de meest recente waarde retourneren.

Verzoekhandtekeningen in workflow webhooks controleren

Als 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 het app-secret voor je applicatie, de HTTP-methode, de URI en de ongeparsde body. Lees meer hierover in de documentatie voor ontwikkelaars.

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

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

Workflows van webhooks triggeren

Webhooks kunnen worden gebruikt om workflows te triggeren. Wanneer gegevens in een app van derden veranderen, kan dit een workflow triggeren. Meer informatie over het triggeren van workflows via webhooks.

Webhookgegevens gebruiken in het gegevenspaneel

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

Om gegevens van de verbonden webhook te gebruiken:

1. Ga in je HubSpot-account naar Automatisering > Workflows.
2. Klik op de naam van uw workflow.
3. Klik op het plus-pictogram om een actie toe te voegen.
4. Selecteer in het linkerpaneel een actie die het gegevenspaneel gebruikt.
5. Klik in het gegevenspaneel op de View properties of action outputs from dropdown menu en selecteer Webhook trigger. Je kunt dan eigenschappen van de gekoppelde webhook gebruiken.