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: 


Karakterset

De data moet aangeleverd worden in de karakterset: UTF-8


Hier kan je ook kiezen voor de juiste authenticatie:



Als de data verzonden is, ontvang je een bevestiging in de wizard. 


Stap 4. 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. 

Note

Alle velden in hetzelfde bereik (klanten, datamodel) moeten hetzelfde pad hebben. Als je dus een pad maakt met wildcards moet elk pad hetzelfde aantal wildcards hebben. 

Geslacht

Het sekse veld met het geslacht verwacht de volgende waardes: MAN, WOMAN, FAMILY, NONBINARY of UNKNOWN.

Deze gegevens kunnen op deze manier worden aangeleverd of middels een translate plugin worden vertaald in de webhook mapping. 

Opt-in

De opt-invelden verwachten de volgende waarden: Y (Yes) or N (no)

Let op! Als je géén opt-in waarde mapt, dan is de standaard waarde Y (Yes).

Yes/No

Wanneer in de datamodel definitie een Yes/No kolom is aangemaakt, dan verwacht Deployteq de volgende waardes: 1 (Yes) of 0 (no)

Als je tevreden bent over jouw mapping, klik op opslaan in de linkerbovenhoek en klik naar de volgende stap.

Stap 5. 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. 

Webhook Mapping

Bekijk voor meer details onze documentatie: Webhook Mapping. 



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. 

Beschikbaarheid logs

Alle informatie in de log wordt voor een periode van een week opgeslagen. 

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

BODY request 
{
"firstname": "Sophie",
"gender": "WOMAN",
"email": "s.kumpen@domein.nl",
"anything": "give me some data",
"newsletter_optin": "Y"
}


BODY response 
{
"firstname": "Sophie",
"gender": "WOMAN",
"email": "s.kumpen@domein.nl",
"anything": "give me some data",
"newsletter_optin": "Y",
"__customer__id__": 19
}

Uitgebreide order call

BODY request 
{
"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"
        	}
        	]
        }
}
BODY response 
{
"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

BODY request 
{
	"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"
			}
    ]
}


BODY response 
{
	"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
			}
    ]
}

Batches versturen

Wij adviseren om bij het werken met batches de reactietijd onder 1 minuut te houden voor een optimale werking. 

Mailbaarheid bij batches

In Deployteq wordt in het geval van batches gecontroleerd op de mailbaarheid van de records alvorens een e-mail wordt verstuurd. Als het een transactionele e-mail betreft welke verstuurd moet worden, dan kan het dus voorkomen dat er minder emails verstuurd worden doordat de records niet mailbaar zijn.

Error messages

400 Bad request 
{
    "error": "Unsupported API call"
}
401 Unauthorized 
{
    "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.

429 limit reached 
{
    "error": "Daily limit reached"
}
500 Internal server error 
Internal Server Error
Unsupported API call