Wil je jouw website of systeem koppelen aan het Deployteq platform? Transactionele mails maken met de templates en tooling die je gewend bent? Direct de klant- en orderdata opslaan in het datamodel? Met onze webhook ontvanger is dit erg eenvoudig en geregeld in een paar minuten.
Inhoud
Jouw eerste connectie opzetten
Ga in Deployteq naar de Deployteq Store module in het menu aan de linkerkant. Hier staan alle apps die voor jou beschikbaar zijn. Selecteer de Webhook in het overzicht.
Stap 1. Webhook naam
Volg de vijf stappen-wizard om de webhook ontvanger te installeren. In de eerste stap geef je jouw webhook een naam. In het voorbeeld hieronder is dit demo-manual genoemd:
Stap 2. Authenticatie
In de volgende stap kan je aangeven welke authenticatiemethode je wilt gebruiken. Onder de afbeelding staat uitgelegd wat de verschillende methodes betekenen;
Token
De Deployteq token verwacht de header;
"Authorization" : "Bearer <token>"
De token krijg je bij het installeren van de webhook en na het kiezen van Token als authenticatiemethode. Dit is de unieke token voor deze webhook. Je kunt ook een gebruikerstoken gebruiken voor de webhook. Een gebruikerstoken kan meerdere webhooks aanroepen, want voor één systeem wel handig kan zijn. Het gevaar hiervan is wel dat als het gebruikersaccount waarop de token is aangemaakt wordt verwijderd of inactief raakt (na bijvoorbeeld 60 dagen geen activiteit te hebben vertoond), de webhooks niet meer kunnen worden aangeroepen. Een token kan niet meer worden aangepast, dus als het token uitlekt, zullen alle webhooks opnieuw geinstalleerd moeten worden met nieuwe tokens.
Hier vind je meer informatie over het aanmaken van een token op een gebruikersaccount in Deployteq: Koppelingen met andere software.
Basic Authentication
Als je kiest voor Basic Authentication, verwacht Deployteq de header:
"Authorization": "Basic <base64 user:password>" De 'hash' bestaat uit een user:password die base64 geëncodeerd is, waar we voor het password een token aanmaken specifiek voor deze webhook (dus je kan daar geen andere webhooks en API's mee aanroepen). In de volgende stap geven we je de hash om te gebruiken. Ook hier is het mogelijk een token te gebruiken die voor een gebruiker in Deployteq is, zodat je toegang krijgt tot de API's die aan je gebruiker gekoppeld zijn.
De volgende opties worden alleen getoond als de additionele app hiervoor is ingericht:
TLS Certificate
Met tweezijdige SSL Certificaat authenticatie kan je inkomende en uitgaande API verzoeken ondertekenen en valideren. Deze authenticatie methode kan ook toegepast worden op je eigen webhooks, zie voor meer informatie de handleiding.
OAuth 2
De Deployteq Webhook kan gevalideerd worden met OAuth 2.0. Ook hier is een uitgebreidere uitleg van beschikbaar: Oauth 2.0 Server for Deployteq webhooks
Stap 3. Stuur data
Na het kiezen van de authenticatie krijg je de Endpoint en eventuele extra informatie vanuit jouw gekozen authenticatie en bezit je alle informatie om de eerste dataset te versturen naar het endpoint:
Stuur de data naar de door jou gecreëerde endpoint. Voor de eerste call kun je eventueel een tool zoals Postman gebruiken om verzoeken vanaf je eigen systeem te versturen. In het onderstaand voorbeeld wordt een eenvoudige orderbevestiging verstuurd:
Hier kan je ook kiezen voor de juiste authenticatie:
Als de data verzonden is, ontvang je een bevestiging in de wizard.
Stap 3. Opzetten van data mapping
Als de eerste dataset is ontvangen kan je een standaard mapping definieren voor het verwerken van de gegevens in Deployteq. Daarbij is het mogelijk om klant- en/of datamodelgegevens op te slaan. Bekijk voor meer details onze documentatie hierover: Webhook Mapping.
Klik op 'Open data mapping' om te starten.
De data kan gekoppeld worden naar de klant- en klantoptievelden, maar ook naar het datamodel en de campaign environment velden om je flow mee te bepalen. Hover over een veld om te mappen en klik op de plus '+'. Kies, wanneer je jouw data koppelt, op welke velden je wil ontdubbelen. De velden die je aanmerkt als uniek (unique) krijgen een sleuteltje achter de naam.
Als je tevreden bent over jouw mapping, klik op opslaan in de linkerbovenhoek en klik naar de volgende stap.
Stap 4. Facturatie
In stap 4 is het mogelijk om te kiezen voor maandelijkse of jaarlijkse factureringscyclus. De maandelijkse versie wordt op de eerste van de volgende maand afgeschreven. Bij de jaarlijkse versie wordt het volledige jaarbedrag afgeschreven in de maand die volgt op de maand waarin de webhook geïnstalleerd is. Het is ook mogelijk om een aankoop/ordernummer toe te voegen. Handig als dit verplicht is binnen jouw organisatie en zo niet, dan kan je het veld leeg laten.
Nadat je hebt geklikt op Next heb je een succesvolle verbinding gemaakt. Nu kun je campagnes creëren en logs bekijken.
Dagelijks limiet
Er is een dagelijks limiet van 50.000 verzoeken per dag en per brand ingesteld op de standaard webhook ontvanger. Op hoeveel verzoeken je zit, komt terug in de response headers van het verzoek X-Deployteq-Request-Count;
Als het limiet is bereikt, dan zullen opvolgende verzoeken niet worden verwerkt en een HTTP statuscode 429 worden teruggekoppeld.
Wanneer je verwacht (tijdelijk) meer te gaan doen, installeer dan ook de Webhook Pro app. Deze app kan je naast de bestaande webhooks installeren en die blijven gebruiken zoals je eerder al deed, alleen dan zonder het daglimiet.
Campagnes creëren
Ga naar de campagne designer en creëer een nieuwe campagne. Hier zul je zien dat je een nieuw campagne object tot je beschikking hebt, genaamd 'start on webhook'.
Wanneer je een enkele webhook hebt geïnstalleerd, hoef je alleen maar het object te bevestigen. Jouw webhook is nu ready to go. Als je meerdere webhooks hebt, selecteer je het juiste endpoint in de dropdown. Wanneer een environment in de mapping wordt geïdentificeerd, zie je deze in het startobject verschijnen.
Vanuit het start-object kun je direct een email verzenden. Deployteq zal de opgeslagen data naar het start-object sturen, inclusief de opgeslagen order in jouw selectie om deze data ook in de mail te gebruiken. Een bevestigingscampagne kan daarom zo simpel zijn:
Mappings aanpassen
Als je teruggaat naar de Deployteq Store, zie je jouw geïnstalleerde apps terug bovenin het overzicht:
Selecteer de webhook die je wil aanpassen en klik op de derde stap in de wizard om naar de mappings te gaan. Hier kan je opnieuw de velden mappen die je uit de laatste call hebt ontvangen. Als je een veld wil toevoegen aan deze call, stuur het naar Deployteq en je kan de bijpassende Deployteq-velden mappen.
Logs gebruiken
Wanneer je wil zien welke calls er zijn verzonden naar Deployteq, welke details er zijn opgeslagen of om te zien of een campagne is getriggerd, kun je dit terug zien in de logs. Als je naar de webhook configuratie gaat, kun je de button 'View/bekijk logs' aanklikken. Je ziet nu de calls naar de webhook in chronologische volgorde.
Aan de rechterkant vind je de volgende drie iconen:
. Van links naar rechts hebben deze iconen de volgende functies:
- Opslaan; je kan de data opnieuw opslaan met dezelfde call. Wanneer je de mappings hebt aangepast, hoef je dus geen nieuwe call in te stellen. Je hoeft alleen maar op opslaan te klikken en alle data wordt opnieuw opgeslagen.
- Afspelen; door hier op te klikken, trigger je de campagne opnieuw. Als je mails of campagnes hebt gewijzigd, kun je de opgeslagen klant opnieuw naar de campagne sturen. Let op: als je ook je mapping hebt aangepast, sla dan eerst op en trigger daarna de campagne opnieuw.
- Info; hiermee kun je de data van de call inzien. Je kan zien hoe vaak de data is opgeslagen of hoe vaak de campagne is getriggerd. Met de buttons aan de rechterkant, kun je deze interface ook opslaan of triggeren.
Filters in de webhook log
Het is ook mogelijk om de resultaten van het log te filteren, klik op het pijltje van de kolom waarop gefilterd moet worden en kies voor de optie "filter". Afhankelijk van de inhoud van de gekozen kolom kan een filter worden ingesteld voor de betreffende kolom.
Voorbeeld calls
De webhook is gemaakt om alles te accepteren dat een standaard JSON-format heeft. Hier volgt een aantal voorbeelden hoe data naar de webhook gestuurd kan worden.
Eenvoudige call
{
"firstname": "Sophie",
"gender": "WOMAN",
"email": "s.kumpen@domein.nl",
"anything": "give me some data",
"newsletter_optin": "Y"
}{
"firstname": "Sophie",
"gender": "WOMAN",
"email": "s.kumpen@domein.nl",
"anything": "give me some data",
"newsletter_optin": "Y",
"__customer__id__": 19
}Uitgebreide order call
{
"firstname": "Sophie",
"surname": "Kumpen",
"gender": "WOMAN",
"email": "s.kumpen@domein.nl",
"flag": "orders",
"anything": "more data",
"campaign": "transactional",
"order": {
"order_id": "5234",
"total": "49.5",
"shipping": "5",
"date": "2017-08-24",
"status": "Delivered",
"payment": "iDeal",
"products": [
{
"articleID":"123",
"name": "Product1",
"price": "21.5",
"category":"sneakers",
"color": "white",
"size": "38"
},
{
"articleID":"456",
"name": "Product2",
"price": "88.25",
"category":"pumps",
"color": "purple",
"size": "38"
}
]
}
}{
"firstname": "Sophie",
"surname": "Kumpen",
"gender": "WOMAN",
"email": "s.kumpen@domein.nl",
"flag": "orders",
"anything": "more data",
"campaign": "transactional",
"order": {
"order_id": "5234",
"total": "49.5",
"shipping": "5",
"date": "2017-08-24",
"status": "Delivered",
"payment": "iDeal",
"products": [
{
"articleID":"123",
"name": "Product1",
"price": "21.5",
"category":"sneakers",
"color": "white",
"size": "38",
"__ordered_items__id__": 15
},
{
"articleID":"456",
"name": "Product2",
"price": "88.25",
"category":"pumps",
"color": "purple",
"size": "38",
"__ordered_items__id__": 16
}
],
"__orders__id__": 2
},
"__customer__id__": 19,
"__orders__id__": 2
}Meerdere klanten in 1 verzoek
{
"contacts":[
{
"firstname": "Sophie",
"surname": "Kumpen",
"gender": "WOMAN",
"email": "s.kumpen@domein.nl",
"newsletter_optin": "Y"
},
{
"firstname": "Angelo",
"surname": "van der Kleij",
"gender": "MAN",
"email": "a.vanderkleij@domein.nl",
"newsletter_optin": "N"
}
]
}{
"contacts":[
{
"firstname": "Sophie",
"surname": "Kumpen",
"gender": "WOMAN",
"email": "s.kumpen@domein.nl",
"newsletter_optin": "Y",
"__customer__id__": 19
},
{
"firstname": "Angelo",
"surname": "van der Kleij",
"gender": "MAN",
"email": "a.vanderkleij@domein.nl",
"newsletter_optin": "N",
"__customer__id__": 23
}
]
}Error messages
{
"error": "Unsupported API call"
}{
"error": "Unauthorized session"
}Bovenstaande 401 response komt meestal doordat de User gegevens (token en useraccount combinatie) niet meer bestaan of dat de user is gedisabled. Neem hiervoor contact op met je Portal Admin of met onze support desk via support@deployteq.com om dit issue te verhelpen.
{
"error": "Daily limit reached"
}Internal Server Error
Unsupported API call