Intro Releasenotes Documentatie & testen ClientID Access Token Webhooks Postman Best practices Unauthorized(401) Forbidden(403) Limiet Bereikt (429) Meldingen FAQ Terminologie Use case: bijwerken persoon Use case: niet beschikbaarheid Use case: aanbod op website Use case: inschrijving versturen Datamodel
| Wanneer je met API's van Coachview een koppeling realiseert, dan ga je op bepaalde tijdstippen, bijvoorbeeld elk uur, gegevens ophalen uit Coachview of wegschrijven in Coachview. Met een webhook, ook wel reverse API genoemd, is het mogelijk om gegevens vanuit Coachview te 'pushen'. Dat betekent dat Coachview elk moment een bericht (webhook) kan sturen en dat op basis van dat bericht een vervolgactie bepaalt kan worden in de jouw applicatie. | ||||||||||||||||||||||||||||||||||||||||
Voorbeeld: | ||||||||||||||||||||||||||||||||||||||||
| Wanneer een persoon is aangemaakt in Coachview kan daar een bepaalde categorie aan toegevoegd worden. De wens is om vanuit jouw applicatie elke persoon die deze categorie heeft een document met zijn verantwoordelijkheden te sturen. Maak je gebruik van een API dan kan elk uur gecontroleerd worden of er een persoon is waarbij de betreffende categorie toegevoegd is. Op basis van het antwoord kan dan de vervolgactie uitgevoerd worden. Het kan dus voorkomen dat het 59 minuten duurt voordat de vervolgactie uitgevoerd wordt. Maak je gebruik van een webhook, dan wordt er automatisch een bericht naar jouw applicatie (URL) gestuurd op het moment wanneer de categorie aan een persoon toegevoegd wordt. De vervolgactie kan dan direct uitgevoerd worden. | ||||||||||||||||||||||||||||||||||||||||
Benodigde informatie: | ||||||||||||||||||||||||||||||||||||||||
| Deze informatie is er nodig om webhooks te activeren. | ||||||||||||||||||||||||||||||||||||||||
| URL: De webhook zorgt ervoor dat Coachview een bericht stuurt op basis van een bepaalde gebeurtenis. Dit bericht wordt naar een URL gestuurd. We hebben dus de URL nodig waar dit bericht naar toe gestuurd moet worden. Een voorbeeld is: HTTPS://voorbeeldklant.nl Bij deze URL is het belangrijk dat poort 443 gebruikt wordt. Dit is de standaard poort voor HTTPS. Coachview ondersteunt geen andere poort vanwege veiligheid. De authenticatie is anonymous authentication. Coachview ondersteunt geen basic authentication. Wanneer je gebruik wil maken van meerdere webhooks, dan is het mogelijk dat deze op een andere URL afgeleverd wordt. Het voordeel van een aparte URL per webhook is dat per webhook andere instellingen meegegeven kunnen worden. Denk daarbij aan PII, details en signatures. Deze instellingen worden later in dit document toegelicht. Daarnaast weet je met aparte URL's ook precies wanneer welke webhook binnengekomen is. Daardoor is het niet meer nodig om een extra filter/controle toe te voegen. Abonnementen Je hebt een apart abonnement nodig wanneer je meerdere URL's, token of signingscrets wil gebruiken. Voor PII (Personally Identifiable Information) en Details heb je dat niet nodig. | ||||||||||||||||||||||||||||||||||||||||
Gebeurtenis: | ||||||||||||||||||||||||||||||||||||||||
| Op https://training.coachview.net/apidocs/swagger/index.html#/ vind je de beschikbare webhooks bij sectie "Webhooks". | ||||||||||||||||||||||||||||||||||||||||
| Je ziet daar een lijst staan met de gebeurtenissen. Wij ontvangen graag van je de naam van de gebeurtenissen waar je gebruik van wil maken. In het geschetste voorbeeld zou dat betekenen dat je de webhook 'persoon categorie toegevoegd' nodig hebt. | ||||||||||||||||||||||||||||||||||||||||
Beveiliging: | ||||||||||||||||||||||||||||||||||||||||
| Er zijn twee methoden om te valideren of de webhook afkomstig is van Coachview: Handtekening/signature: In de httpheader 'X-coachview-whsignature' staat een handtekening/signature die is berekend over het gehele bericht met HMAC-SHA256 en de SigningSecret van de subscription. Deze signature is een base64 string. Token: In de httpheader 'X-coachview-whtoken' staat de 'token' zoals deze is ingesteld in de subscription. Dit is dezelfde waarde zonder signature of berekening. Coachview geeft deze beide terug zodat je zelf kunt bepalen welke je wil gebruiken. De "Handtekening/signature" is de meest veilige methode en heeft ook onze voorkeur. Je bent als klant zelf verantwoordelijk om één van deze twee opties te implementeren. | ||||||||||||||||||||||||||||||||||||||||
Personally Indentifiable Information (PII): | ||||||||||||||||||||||||||||||||||||||||
| De webhook stuurt diverse velden mee naar de gekozen URL. Bij de velden die meegestuurd worden is aangegeven of deze meegestuurd moeten worden wanneer je PII aan hebt staan. Per webhook kun je aangeven of je de velden die gemarkeerd zijn als PII mee wil laten sturen met de webhook of niet. Per webhook dien je aan te geven of je PII wel/niet wil meenemen. | ||||||||||||||||||||||||||||||||||||||||
Details: | ||||||||||||||||||||||||||||||||||||||||
| Voor details geldt hetzelfde als bij de PII. Ook dien je hiervoor per webhook aan te geven of je details wel/niet mee wil nemen. Wanneer je op https://training.coachview.net/apidocs/swagger/index.html#/ kijkt bij de betreffende webhook dan kun je zien welke velden getoond worden bij PII en bij details. | ||||||||||||||||||||||||||||||||||||||||
| Klik op het pijltje bij 'Schema's' helemaal onderaan deze pagina om het overzicht te tonen. | ||||||||||||||||||||||||||||||||||||||||
| Scroll naar beneden tot dat je bijvoorbeeld de webhook 'Er is een nieuwe categorie aan een persoon toegevoegd' tegen komt en klik op de naam. | ||||||||||||||||||||||||||||||||||||||||
Laat ons het volgende weten: | ||||||||||||||||||||||||||||||||||||||||
| Maak het volgende per te gebruiken API aan ons bekend. | ||||||||||||||||||||||||||||||||||||||||
| ||||||||||||||||||||||||||||||||||||||||
Retry mechanisme. | ||||||||||||||||||||||||||||||||||||||||
| Wanneer de webhook verstuurd wordt en deze kan niet afgeleverd worden, dan wordt de webhook nogmaals verstuurd. Wij proberen deze 12x opnieuw te versturen. In totaal sturen wij dus 13x de webhook. Elke keer wordt er langer gewacht tot de volgende keer wordt geprobeerd. Bijvoorbeeld Stel dat de webhook vandaag om 11:45 uur verstuurd wordt. Op welke tijdstippen worden deze dan nogmaals gestuurd indien deze niet afgeleverd kunnen worden?
| ||||||||||||||||||||||||||||||||||||||||
| Let op: geef de status 200 (succes) z.s.m. terug als de webhook ontvangen is. En niet pas als de webhook helemaal is verwerkt. Coachview wacht niet lang op een antwoord. Bij fouten ook een 200 op de webhook teruggeven, anders wordt de webhook opnieuw geprobeerd totdat deze na 10x als mislukt wordt aangemerkt. Coachview onderneemt dan geen actie.
|
Bijgewerkt tot en met versie 85
