Met de generieke koppeling heb je de mogelijkheid behaalde resultaten van cursisten terug te sturen naar Coachview. Dit doe je met behulp van een webhook, maar hoe werkt zo'n webhook en hoe kan ik die testen?

Werkwijze:
Coachview biedt een URL aan waarop een XML-bericht kan worden gepost. Daarbij is de beveiliging erg belangrijk, omdat iedereen naar de betreffende URL een bericht kan sturen. Meer informatie over het terugsturen van het resultaat dien je het document "Resultaten terugsturen naar Coachview" te lezen. In dit document staat beschreven hoe de webhook werkt en hoe je dit kunt testen met bijvoorbeeld Postman.

Beveiliging:
In een HTTP-header (naam ‘X-WebHook-Signature’) dient een signarture/hash te worden opgenomen om te controleren of deze gegevens daadwerkelijk van de zender afkomstig zijn. Er wordt een ‘secret’ afgesproken tussen zender en Coachview. Coachview kan een ‘secret’ genereren.

Over het gehele XML-bericht in de body wordt een HMAC SHA berekend. Coachview berekent ook de HMAC SHA over het bericht. Deze moet overeenkomen met wat door de zender in de HTTP-header wordt meegestuurd. 


LET OP: Deze signature dient een base64 string te zijn. 


Welke informatie heb ik nodig?
De generieke kopppeling stel je in via [Integraties, Integraties, E-Learning, Coachview Generiek].
URL Resultaten:Naar deze URL stuur je de resultaten terug.
Versleuteling resultaten webhook:Geef aan welke HASH je wil gebruiken. Standaard is dit SHA512.
Webhook secret:Geef hier de webhook secret uit het elearningpakket in.

Hoe kun je de webhook testen in Postman?
1. Noteer de gegevens uit het service center.URL resultaten en webhook secret
2. Open Postman en kies voor het aanmaken van een nieuw request.
3. Pas de GET aan naar POST en plaats de URL uit het service center in de balk. Op de plaats van de xxxxx staat bij jullie een andere code. Voor veiligheid is deze nu aangepast naar xxxxxx. In de URL en bij de query params dient dezelfde waarde te staan.
4. Ga naar de "Body", selecteer "raw" en zet deze op "XML". Plak daar jouw XML-bericht in wat je naar Coachview wil sturen.
LET OP! Pas niets aan in het bericht. Wanneer je er bijvoorbeeld een spatie bij zet, dan is het een ander bericht en zal de match niet slagen.
5. Ga naar de "Headers" en voeg een nieuwe header "X-Webhook-Signature" toe zoals hiernaast getoond wordt. Op de plaats van de xxx zet je de code die je berekend hebt. Hoe je deze berekent leg ik hieronder uit.
6. Klik vervolgens op "Send" en je krijgt als je alles goed ingesteld hebt de melding "Webhook registered with id: 12345".

Hoe bereken je de "X-Webhook-Signature"?
1. Genereer de HMAC (hash-based message authentication code". Ga bijvoorbeeld naar https://www.freeformatter.com/hmac-generator.html#before-output of start een andere HMAC generator.

  • Zet in het eerst vak het XML-bericht. Ook hierbij geldt dat je het bericht niet aan moet passen.
  • Bij de "Secret key" vul je de "Webhook secret" in die je in het service center ingesteld hebt.
  • Kies het juiste algorithm, meestal SHA512.

Kies voor "Compute HMAC" en de HMAC wordt voor je gegenereerd.
2. Converteer de code naar base64. De code die je zojuist gegenereerd hebt is hexadecimal. Een eis voor Coachview is dat de signature een base64 string is. Deze hexadecimal kan eenvoudig vertaald worden naar base64. Een snelle manier is om te gaan naar de website https://base64.guru/converter/encode/hex. Hieronder zie je een voorbeeld van de velden op deze website. Dit is een voorbeeld en er ontbreekt een deel van de code, dus deze kan niet gebruikt worden.


Vul bij "Hex" de code in die bij stap 1 (HMAC) gegenereerd is en kies daarna op "Convert Hex to Base64". De code die bij "Base64" staat dien je bij de header "X-Webhook-Signature" in te vullen.

Welke controle wordt door Coachview uitgevoerd?
Beide partijen, dus zowel degene die de webhook stuurt als Coachview berekenen een HMAC SHA512 over het bericht. Deze twee moeten 100% overeenkomen. Komt deze niet overeen, dan krijg je een 403 melding Forbidden.