Naar de hoofdinhoud

Hoe stuur ik met MailBlue gegevens naar een externe partij via een webhook?

In dit artikel wordt uitgelegd hoe je webhooks instelt in MailBlue, welke gegevens je kunt versturen en hoe je ze test.

Geschreven door Team MailBlue
Functionaliteit beschikbaar vanaf het Starter-abonnement

​

​

Wat is een webhook?

Een webhook is een automatisch bericht dat van het ene systeem naar het andere wordt verstuurd wanneer een gebeurtenis plaatsvindt. Met MailBlue kun je gegevens naar een externe database of applicatie sturen, bijvoorbeeld wanneer een contact wordt bijgewerkt, een dealtaak wordt aangemaakt of iemand op een link in een e-mail klikt. Zo kun je activiteiten van contacten, campagnes, deals en aangepaste objecten in de ontvangende applicatie bijwerken.

​

Een webhook is handig wanneer de externe software geen rechtstreekse koppeling met MailBlue ondersteunt. Je kunt bijvoorbeeld gegevens doorgeven wanneer een account wordt toegevoegd of een contactrecord wijzigt.

​

Let op: de ontvangende applicatie moet over een API beschikken en HTTPS POST-verzoeken via de standaard HTTPS-poort (443) accepteren. Je kunt geen inkomende webhooks rechtstreeks aan MailBlue koppelen.

​

​

Op welke manieren kan ik webhooks gebruiken?

Je kunt in MailBlue op twee manieren een webhook instellen. De gekozen methode bepaalt wanneer het verzoek wordt verstuurd en welke opties je kunt instellen.

  • Via een automatisering: vanaf het Plus-abonnement. De 'Webhook'-actie verzendt gegevens wanneer een contact deze stap bereikt. Je hoeft hiervoor geen webhook via 'Instellingen' aan te maken.

  • Via de instellingen: vanaf het Starter-abonnement. Een webhook onder 'Instellingen' > 'Ontwikkelaar' reageert op geselecteerde gebeurtenissen, zoals het bijwerken van een contact of het openen van een campagne. Je kiest daarbij ook waardoor de gebeurtenis wordt geïnitieerd.

​

De nieuwe instellingen voor de 'Webhook'-actie binnen automatiseringen veranderen niets aan de bestaande webhooks onder 'Instellingen' > 'Ontwikkelaar'.

​

​​

Hoe voeg ik een webhook toe aan een automatisering?

Met de 'Webhook'-actie verstuur je contactgegevens naar een URL zodra een contact deze stap in je automatisering bereikt. Je hoeft niet apart in te stellen welke gebeurtenis deze webhook activeert, omdat de automatisering dit bepaalt.

​

Zo vind je de 'Webhook'-actie in het actiemenu van je automatisering:

Schermafbeelding van het actiemenu waarin 'Webhook' onder 'Workflow' is gemarkeerd.

​

  1. Klik in het linkermenu op 'Automatiseringen' en open de gewenste automatisering met 'Bewerken'.

  2. Is de automatisering actief? Pauzeer deze dan voordat je wijzigingen aanbrengt.

  3. Klik op het plusteken (+) op de plek waar je de actie wilt toevoegen.

  4. Kies in 'Actie toevoegen' voor 'Workflow' en daarna voor 'Webhook'.

  5. Vul de HTTPS-URL van de ontvangende applicatie in.

  6. Kies bij 'Uitvoertype' voor 'JSON' of 'x-www-form-urlencoded'.

  7. Voeg zo nodig authenticatie, aangepaste headers of queryparameters toe.

  8. Selecteer bij 'Metadata opnemen' welke gerelateerde gegevens je wilt meesturen.

  9. Klik op 'Opslaan'.

  10. Test de actie met een testcontact en controleer het ontvangen verzoek in de externe applicatie. Activeer de automatisering weer zodra alles werkt zoals verwacht.

​

Let op: pauzeer een actieve automatisering voordat je de webhookactie wijzigt. Zet de automatisering na het testen weer aan, zodat contacten verder kunnen doorstromen.

​

​

Welk uitvoerformaat kan ik voor een webhook kiezen?

Het uitvoertype bepaalt hoe de inhoud van het verzoek naar de ontvangende URL wordt verstuurd. Het bepaalt niet welk antwoord de ontvangende applicatie terugstuurt.

  • 'JSON': verstuurt een JSON-object. Dit is standaard geselecteerd voor nieuwe webhookacties.

  • 'x-www-form-urlencoded': verstuurt formuliergegevens. Kies dit wanneer de ontvangende applicatie dat formaat verwacht.

Wil je van formuliergegevens overstappen op JSON? Kies dan 'JSON', lees de waarschuwing en klik op 'Overschakelen naar JSON'.

​

Let op: een verandering van uitvoertype wijzigt hoe de externe applicatie het verzoek moet verwerken. Controleer daarom eerst of deze applicatie het nieuwe formaat ondersteunt.

​

​

Hoe voeg ik authenticatie en aangepaste headers toe?

Heeft de ontvangende applicatie een geheim in een verzoekheader nodig? Vul dan onder 'Authenticatie' de velden 'Naam' en 'Waarde' in. Vereist de applicatie bijvoorbeeld een bearer-token, gebruik dan Authorization als naam en Bearer YOUR_TOKEN als waarde.

​

Een opgeslagen authenticatiewaarde wordt verborgen wanneer je de actie opnieuw opent. Laat het waardeveld leeg om het opgeslagen geheim te behouden, zolang de URL niet verandert. Wijzig je de URL, vul het geheim dan opnieuw in. Om authenticatie te verwijderen, maak je zowel de naam als de waarde leeg en sla je de actie op.

​

De authenticatiewaarde wordt precies als headerwaarde verstuurd. Met deze instelling maak je geen digitale handtekening van de inhoud van het verzoek. Importeer je een gedeelde automatisering? Vul dan je eigen authenticatiewaarde in.

​

Onder 'Aangepaste headers' kun je extra headerregels invoeren met 'Headernaam' en 'Headerwaarde'. Klik op 'Header toevoegen' om een regel toe te voegen. Je kunt maximaal tien aangepaste headers instellen.

​

Let op: waarden van aangepaste headers blijven zichtbaar wanneer je de actie opnieuw opent. Bewaar geheime waarden daarom onder 'Authenticatie'. Headernamen mogen geen spaties bevatten en mogen niet Content-Type, Content-Length, Host of Transfer-Encoding zijn. De authenticatienaam mag ook niet gelijk zijn aan een aangepaste headernaam.

​

​

Hoe voeg ik queryparameters toe aan een webhook?

Onder 'Aangepaste queryparameters' geef je bij 'Parameter' en 'Waarde' op welke gegevens aan de ontvangende URL worden toegevoegd. Met 'Queryparameter toevoegen' maak je een extra regel.

​

Je kunt personalisatietags in parameterwaarden gebruiken. Vul bijvoorbeeld email in als parameter en %EMAIL% als waarde. MailBlue vult dan voor ieder contact het e-mailadres in en codeert de waarde voor gebruik in de URL.

​

Opgeslagen parameters worden toegevoegd na eventuele parameters die al in de URL staan. Ook wanneer een waarde een lege tekst oplevert, wordt de parameter verstuurd. Je kunt personalisatietags eveneens rechtstreeks in de URL laten staan.

​

Bij accounttags worden accountgegevens gebruikt als die beschikbaar zijn. Bij dealtags wordt de deal gebruikt die de automatisering heeft geactiveerd, als die beschikbaar is. Anders gebruikt MailBlue de meest recent aangemaakte deal van het contact. Dit werkt anders dan de optie 'Deals' bij de metadata, waarmee gekoppelde dealrecords worden meegestuurd.

​

Gebruik 'Authenticatie' voor geheime waarden, niet queryparameters. Queryparameters worden onderdeel van de ontvangende URL.

​

​

Welke contactgegevens en metadata worden meegestuurd?

Een webhookactie in een automatisering verstuurt altijd de basisgegevens van het contact en het ID van de automatisering (seriesid). De basisgegevens omvatten contact-ID, e-mailadres, voornaam, achternaam, telefoonnummer en de velden voor de accountnaam. Als een IPv4-adres beschikbaar is, wordt ook ip4 meegestuurd.

​

Onder 'Metadata opnemen' kun je kiezen welke extra groepen je meestuurt:

  • 'Eigen velden': de waarden van de eigen velden van het contact.

  • 'Lijsten': lijst-ID's, lijstnamen en abonnementsstatussen van het contact.

  • 'Tags': de namen van de tags van het contact.

  • 'Accounts': de ID's en namen van gekoppelde accounts.

  • 'Deals': gekoppelde deals met ID's, titels, waarden, valuta's, statussen en fasen.

  • 'Aangepaste objecten': gekoppelde records van aangepaste objecten waartoe je account toegang heeft.

Bij nieuwe webhookacties is 'Eigen velden' standaard geselecteerd. Alle andere metagegevensgroepen staan standaard uit. Je kiest telkens een volledige groep. Je kunt de inhoud van het verzoek niet vrij veld voor veld opbouwen.

​

​

Hoe ziet de inhoud van een webhookverzoek eruit?

Bij 'JSON' staan de basisgegevens onder contact en het automatiserings-ID onder seriesid. Geselecteerde gegevensgroepen worden daarnaast toegevoegd als custom_fields, lists, tags, accounts, deals en custom_objects.

​

Hieronder zie je een verkort JSON-voorbeeld waarin 'Eigen velden' en 'Tags' zijn geselecteerd:

{   "contact": {     "id": "123",     "email": "[email protected]",     "first_name": "Alex",     "last_name": "Morgan",     "phone": "",     "orgname": "Example Co",     "customer_acct_name": "Example Co"   },   "seriesid": "456",   "custom_fields": {     "preferred_color": "Blue",     "job_title": null   },   "tags": ["Customer"] }

​

De waarden en ID's in je eigen verzoek kunnen afwijken. Sleutels van eigen velden gebruiken de personalisatietagnaam in kleine letters. Niet-geselecteerde groepen ontbreken. Geselecteerde groepen zonder records worden lege arrays ([]), terwijl lege eigen velden een leeg object ({}) vormen. Lege tekstwaarden van eigen velden worden in JSON null.

​

Een record van een aangepast object bevat id, schema_id en fields. Als MailBlue deze gegevens niet kan ophalen, ontbreekt custom_objects in het verzoek. Dit betekent niet automatisch dat er geen records zijn.

​

Bij 'x-www-form-urlencoded' is de structuur anders: eigen velden staan onder contact[fields], tags worden als kommagescheiden waarde verstuurd onder contact[tags], en geselecteerde lijsten, accounts, deals en aangepaste objecten staan in eigen hoofdgroepen. Lege groepen worden bij formuliergegevens weggelaten.

​

​

Hoe werk ik een bestaande webhookactie bij?

Oude webhookacties waarin je alleen een URL kon invoeren blijven hun bestaande formulierformaat en contactgegevens gebruiken zolang je ze niet bewerkt en opslaat. Open je zo'n actie, dan staat 'x-www-form-urlencoded' geselecteerd en zijn de metagegevensgroepen niet aangevinkt.

​

Let op: controleer vóór het opslaan van een oude actie onder 'Metadata opnemen' welke groepen je nodig hebt. Zelfs als je het formulierformaat behoudt, kunnen na het opslaan velden uit het oude verzoek ontbreken. Test de webhook daarom na iedere wijziging van het formaat of de gegevensselectie.

​

Zie je bij een webhookactie alleen het URL-veld? Dan zijn de uitgebreide instellingen nog niet ingeschakeld voor je account. Je kunt de bestaande URL-only actie blijven gebruiken.

Welke typen webhooks kan ik via de instellingen gebruiken?

Via 'Instellingen' > 'Ontwikkelaar' kun je webhooks aanmaken voor standaardobjecten en aangepaste objecten. De beschikbare objecttypen en gebeurtenissen hangen af van je abonnement. Sommige accounts hebben beide typen, andere alleen standaardwebhooks.

​

Standaardobjectwebhooks verzenden gegevens bij gebeurtenissen rond contacten, deals, accounts, campagnes en websites. Welke standaardobjecten beschikbaar zijn, hangt af van je abonnement.

​

Webhooks voor aangepaste objecten verzenden gegevens wanneer er iets gebeurt met een aangepast object. Het kan gaan om objecten uit een ondersteunde koppeling of objecten die je hebt aangemaakt via de API of via 'Gegevens beheren' in je account.

​

Voor Shopify en WooCommerce worden de volgende gebeurtenissen met aangepaste objecten ondersteund, voor zover deze functionaliteit voor je account beschikbaar is:

  • Bestellingen: aangemaakt, bijgewerkt of verwijderd.

  • Producten: aangemaakt, bijgewerkt of verwijderd.

Welke gebeurtenissen kan ik via de instellingen doorgeven?

Voor webhooks via 'Instellingen' kun je verschillende soorten gebeurtenissen selecteren:

  • Account: toegevoegd of bijgewerkt.

  • Campagne: doorgestuurd, geopend, gedeeld of gestart met verzenden.

  • Contact: toegevoegd of bijgewerkt, aan een account toegevoegd of daarvan bijgewerkt of verwijderd, notitie toegevoegd, tag toegevoegd of verwijderd, taak toegevoegd of uitgeschreven.

  • Deal: toegevoegd of bijgewerkt, notitie toegevoegd, pijplijn toegevoegd, fase toegevoegd, taak toegevoegd of voltooid, of taaktype toegevoegd.

  • E-mail: gebouncet of beantwoord.

  • Link: aangeklikt.

  • Lijst: toegevoegd.​

​

Hoe maak ik een webhook aan via de instellingen?

Met standaardwebhooks via 'Instellingen' kun je vanaf Starter gegevens naar een externe partij sturen zodra een geselecteerde gebeurtenis plaatsvindt. Deze methode staat los van de 'Webhook'-actie in een automatisering.

​

Je vindt de webhooks onder 'Instellingen' > 'Ontwikkelaar' > 'Beheer webhooks'. Hier zie je waar je webhooks kunt beheren:

Schermafbeelding van de pagina 'Ontwikkelaar' met de optie 'Beheer webhooks' gemarkeerd.

​

Hoe stel je een standaardobjectwebhook in?

  1. Klik op het tandwiel en open 'Instellingen'.

  2. Klik in het linkermenu op 'Ontwikkelaar'.

  3. Klik op 'Beheer webhooks' en vervolgens op 'Toevoegen'.

  4. Kies het type webhook dat je wilt aanmaken.

  5. Vul een naam in en geef bij 'URL' het adres van de ontvangende applicatie op.

  6. Kies onder 'Type' welke gebeurtenis of gebeurtenissen de webhook activeren. Je kunt meerdere gebeurtenissen selecteren.

  7. Selecteer waardoor de gebeurtenis wordt geïnitieerd, bijvoorbeeld door een contact, een accountgebruiker, een systeemproces of een API-aanroep.

  8. Selecteer zo nodig de lijst waarmee de webhook is verbonden. Dit veld verschijnt alleen als het gekozen webhooktype een lijst vereist.

  9. Klik op 'Opslaan'.

​

Hoe stel je een app- of aangepaste webhook in? Bij deze typen doorloop je dezelfde eerste stappen via 'Instellingen' > 'Ontwikkelaar' > 'Beheer webhooks' > 'Toevoegen'. Vervolgens geef je de volgende gegevens op:

  1. Geef de webhook een naam.

  2. Selecteer bij 'Type' de gebeurtenis of gebeurtenissen die de webhook activeren.

  3. Vul bij 'URL' het adres van de ontvangende partij in.

  4. Klik op 'Opslaan'.

​

Hoe stel je een e-commercewebhook voor aangepaste objecten in? Nadat je dit type hebt gekozen, geef je de volgende gegevens op:

  1. Geef de webhook een naam.

  2. Vul het adres van de ontvangende partij in bij 'URL'.

  3. Selecteer bij 'Gebeurtenissen' één of meer gebeurtenissen die de webhook activeren.

  4. Klik op 'Opslaan'.

​

Waardoor kan een webhook via de instellingen worden geactiveerd?

Wanneer je een webhook bij 'Instellingen' > 'Ontwikkelaar' aanmaakt, kies je wanneer deze moet worden uitgevoerd. Hiervoor zijn de volgende opties beschikbaar:

  • Door een contact: wanneer een contact een gebeurtenis veroorzaakt, bijvoorbeeld door een campagne te openen.

  • Door een gebruiker: wanneer een beheerder een actie in het account uitvoert, bijvoorbeeld een contact toevoegen.

  • Door systeemprocessen: wanneer een automatisch systeem de actie uitvoert, bijvoorbeeld bij een gebouncete e-mail.

  • Door de API: wanneer een API-aanroep de actie veroorzaakt, bijvoorbeeld bij het toevoegen van een contact via de contact_add-aanroep.

​

Hoe test ik of een webhook werkt?

Webhook via de instellingen: ga naar 'Instellingen' > 'Ontwikkelaar' > 'Webhooks' en klik op 'Verzend voorbeeldgegevens'. MailBlue verstuurt dan testgegevens naar de URL die je voor de webhook hebt opgegeven.

​

Webhook in een automatisering: gebruik een testcontact dat de 'Webhook'-actie doorloopt. Controleer vervolgens in de ontvangende applicatie of het HTTPS POST-verzoek, het uitvoerformaat en de meegestuurde gegevens kloppen. Zet de automatisering daarna zo nodig weer aan.

​

​

Hoe worden de webhookgegevens ontvangen?

MailBlue verstuurt webhookgegevens als een HTTPS POST-verzoek naar de URL van de ontvangende partij. Bij webhooks via de instellingen worden gegevens als POST-parameters verstuurd. Bij de automatiseringsactie hangt de structuur van de verzoekinhoud af van het gekozen uitvoertype: JSON of formuliergegevens.

​

Voor webhooks via de instellingen garandeert MailBlue dat een webhook minstens één keer wordt afgeleverd. Soms kan hetzelfde verzoek voor één gebeurtenis dus meer dan één keer worden verstuurd.

​

Houd er in de ontvangende applicatie rekening mee dat een gebeurtenis meerdere keren kan binnenkomen. Zo voorkom je dat één gebeurtenis onbedoeld meerdere keren wordt verwerkt.

​

​

Hoe kan ik webhooks via de instellingen met headers beveiligen?

Voor platformwebhooks via de instellingen kun je via de webhook-API aangepaste verzoekheaders opgeven wanneer je een webhook aanmaakt of bewerkt. Deze API-instellingen zijn gescheiden van de instellingen voor de 'Webhook'-actie in een automatisering.

​

Elke API-header bevat een name, een value en is_signature. Er zijn twee varianten:

  • Standaardheader: verstuurt de opgegeven waarde ongewijzigd, bijvoorbeeld voor authenticatie of aanvullende informatie voor de koppeling.

  • Ondertekeningsheader: wanneer je is_signature op true zet, gebruikt MailBlue de opgegeven waarde als geheim om op basis van de inhoud van het webhookverzoek een HMAC-SHA256-handtekening te berekenen. De berekende handtekening wordt als headerwaarde verstuurd. Je kunt maximaal één ondertekeningsheader instellen.

​

De ontvangende partij kan met de ondertekeningsheader controleren of het verzoek van MailBlue komt en onderweg niet is gewijzigd. Het veld 'Authenticatie' in een automatiseringswebhook verstuurt alleen de ingevulde headerwaarde en maakt geen HMAC-handtekening.

​

​

Welke tekens en limieten gelden voor webhooks?

Voor een webhook-URL kun je letters en cijfers gebruiken, plus de volgende speciale tekens: $-_.+!*' (),.

​

Volgens de bestaande MailBlue-documentatie is er geen limiet aan het aantal tekens dat in een notitie of ander veld van een webhook kan worden opgenomen.

​

​

Wat kan ik doen als een webhook niet werkt?

Controleer de ontvangende HTTPS-URL, of de applicatie POST-verzoeken via poort 443 accepteert, welk uitvoerformaat wordt verwacht en of de authenticatie en headers kloppen. Test de webhook vervolgens opnieuw.

​

De supportafdeling van MailBlue kan algemeen advies geven over de inrichting van een webhook, maar kan problemen met de externe verwerking niet voor je oplossen. Schakel zo nodig een technische partij in.

​

​

Veelgestelde vragen

Kan ik een webhook gebruiken met het Starter-abonnement?

Ja, je kunt vanaf Starter webhooks instellen via 'Instellingen' > 'Ontwikkelaar'. Voor de 'Webhook'-actie in automatiseringen heb je minimaal Plus nodig.

Kan ik zelf bepalen welke velden een automatiseringswebhook verstuurt?

Je kunt bij 'Metadata opnemen' volledige gegevensgroepen aan- of uitzetten. Een vrij bewerkbare verzoekinhoud of selectie per afzonderlijk veld is niet beschikbaar.

Wat is het standaardformaat voor een nieuwe webhookactie?

Nieuwe webhookacties gebruiken standaard 'JSON' en sturen 'Eigen velden' mee. Andere metagegevensgroepen zijn standaard uitgeschakeld.

Wat gebeurt er wanneer ik een bestaande webhookactie opsla?

Bij een oudere URL-only actie kunnen na het opslaan bepaalde velden uit het eerdere verzoek ontbreken. Controleer de metadata en test de actie opnieuw.

Kan MailBlue zelf een inkomende webhook ontvangen?

Nee, je kunt geen inkomende webhooks rechtstreeks aan MailBlue koppelen. De hier beschreven webhooks versturen gegevens vanuit MailBlue naar een externe URL.

Waarom ontvang ik dezelfde webhook via de instellingen soms meerdere keren?

Bij platformwebhooks via de instellingen garandeert MailBlue aflevering minstens één keer. Daardoor kan één gebeurtenis meerdere verzoeken opleveren.

Kan ik ook webhooks voor aangepaste objecten gebruiken?

Dat hangt van je abonnement af. Ondersteunde aangepaste objecten komen bijvoorbeeld uit gekoppelde apps of uit objecten die via de API of 'Gegevens beheren' zijn gemaakt.

Wat is het verschil tussen een ondertekeningsheader en authenticatie in een automatisering?

Bij een platformwebhook kun je via de API een HMAC-SHA256-handtekening laten berekenen met is_signature. Bij een automatiseringswebhook wordt de authenticatiewaarde alleen letterlijk als header verstuurd.

Was dit een antwoord op uw vraag?