Wat dit API-eindpunt doet

Webhook-evenementen verzenden informatie over het voltooien van een cursus, het indienen van een cursus voor publicatie, de inschrijving van gebruikers en groepen in cursussen en leertrajecten, of wanneer een gebruiker is toegevoegd aan uw Reach 360-account. Gebruikers configureren de Webhooks API om de informatie op te halen die door deze gebeurtenissen is verzameld.

Soorten evenementen

• course.completed- Wordt geactiveerd wanneer een cursist een cursus voltooit.
• course.submitted- Wordt geactiveerd wanneer een maker een cursus indient die door een beheerder moet worden beoordeeld voor publicatie.
• enrollments.created- Wordt geactiveerd wanneer gebruikers of groepen deelnemen aan een cursus of leerweg.
• user.created- Wordt geactiveerd wanneer een gebruiker wordt toegevoegd aan uw Reach 360-account.

Payload voor Webhook-evenementen

De payload van elk webhook-verzoek heeft een gemeenschappelijke structuur die door alle webhook-evenementen wordt gedeeld. De hoofdtekst van het verzoek bevat de volgende eigenschappen:

• id(string) - de unieke identificator van de gebeurtenis
• createdAt(string) - het tijdstip waarop de gebeurtenis plaatsvond
• type(string) - het webhook-eventtype
• webhookId(string) - de id van de webhook die ertoe heeft geleid dat de gebeurtenis is verzonden
• apiVersion(string) - API-versie die wordt gebruikt bij het verzenden van de webhook-gebeurtenis. Wordt ook als API-Version koptekst in de aanvraag verzonden
• data(object) - specifiek voor het type webhook-eventtype (zie voorbeelden)

Voorbeelden van payloads aanvragen

Elk voorbeeld van een webhook-gebeurtenis hieronder toont een voorbeeld van hoe een webhook-verzoek naar de doel-URL op uw server eruit zou zien.

course.completed

Wordt geactiveerd wanneer een cursist een cursus voltooit.

Eigenschappen van payload-gegevens van gebeurtenissen:

• course (object) - het cursusobject voor de gerelateerde cursus of null als de inschrijvingen betrekking hebben op een leerweg. Dit cursusobject heeft ook een quizobject met twee eigenschappen: geslaagd en score. Als er geen quiz aan de cursus is gekoppeld, is het object leeg.

• user (object) - het gebruikersobject voor de gerelateerde gebruiker.

{
„id”: „voorbeeld-course-completed-event-id”, 
 „createDat”: „2020-07-02T 03:39:18.991 Z”, „type”: „course.completed”, „webhookID”: 
 „
example-webhook-id”, „
APIVersion”: „2023-04-04", „
data”: {„course”: {„authorURL”: "https://api.reach360.com/users/example-author-id „, „coverImageUrl”: null, „id”: „voorbeeld-course-id”, „courseReportURL”: "https://api.reach360.com/reports/courses/example-course-id „, 
 „title”: „
Voorbeeldcursus”, 
 „url”:” 
 
 
 
 https://api.reach360.com/courses/example-course-id „, 
 „contentType”: „RISE” 
 „quiz”: {„geslaagd”: true, 
 „score”: 80
}
}, 
 „user”: {
„email”: "foo@example.com „, „firstName”: „Voornaam voorbeeld”, „groupsURL”: "https://api.reach360.com/users/example-user-id/groups „, 
 „id”: „example-user-id”, „LastName”: 
 „Voornaam”, „LastActiveAt”: 
 „2021-10-28T 20:39:52.659 Z”, 
 „LearnerReportURL”: "https://api.reach360.com/reports/learners/example-user-id „, 
 
„role”: „cursist”, 
 „url”: "https://api.reach360.com/users/example-user-id „, 
 „Articulate360User”: false}}} 
 
 

course.submitted

Wordt geactiveerd wanneer een maker een cursus indient die door een beheerder moet worden beoordeeld voor publicatie.

{
  "id": "example-course-submitted-event-id",
  "createdAt": "2020-09-14T05:47:28.951Z",
  "type": "course.submitted",
  "webhookId": "example-webhook-id",
  "apiVersion": "2023-04-04 ",
  "data": {
    "isInitialSubmission": true,
    "course": {
      "authorUrl": "<https://api.reach360.com/users/example-author-id>",
      "coverImageUrl": null,
      "id": "example-course-id",
      "courseReportUrl": "<https://api.reach360.com/reports/courses/example-course-id>",
      "title": "Example Course",
      "url": "<https://api.reach360.com/courses/example-course-id>",
	  "contentType": "RISE" 
    },
    "submitter": {
      "email": "author@example.com",
      "firstName": "Example",
      "groupsUrl": "<https://api.reach360.com/users/example-author-id/groups>",
      "id": "example-author-id",
      "lastName": "Author",
      "lastActiveAt": "2021-10-28T20:39:52.659Z",
      "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-author-id>",
      "role": "author",
      "url": "<https://api.reach360.com/users/example-author-id>"
 „Articulate360User”: false „Articulate360User”: false 
    },
    "reviewer": {
      "email": "admin@example.com",
      "firstName": "Example",
      "groupsUrl": "<https://api.reach360.com/users/example-admin-id/groups>",
      "id": "example-admin-id",
      "lastName": "Admin",
      "lastActiveAt": "2021-10-28T20:39:52.659Z",
      "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-admin-id>",
      "role": "admin",
      "url": "<https://api.reach360.com/users/example-admin-id>"
 
    }
  }
}

enrollments.created

Wordt geactiveerd wanneer gebruikers of groepen zijn ingeschreven voor een cursus of leerweg.

De payload van deze gebeurtenis bevat altijd dezelfde eigenschapsnamen, maar welke eigenschappen een waarde hebben, hangt af van het type inschrijvingen dat is gemaakt.

Als bijvoorbeeld een of meer gebruikers zijn ingeschreven voor een cursus, bevat het data deel van de payload dat naar uw handler wordt verzonden een users array-eigenschap (een reeks gebruikersobjecten) en een course eigenschap. In dit scenario is de groups eigenschap een lege array en learningPath wordt deze ingesteld opnull.

Op dezelfde manier, als een of meer groepen deelnemen aan een leerweg, zal het data object een groups array-eigenschap (een reeks groepsobjecten) en een learningPath eigenschap hebben, terwijl users het een lege array is en dat course zal zijnnull.

Eigenschappen van payload-gegevens van gebeurtenissen:

• cursus (object) - het cursusobject voor de gerelateerde cursus of null als de inschrijvingen betrekking hebben op een leerweg.
• LearningPath (object) - het leerpadobject voor de gerelateerde leerweg of null als de inschrijvingen voor een cursus zijn.
• EnrolledBy (object) - Het gebruikersobject van de gebruiker die de inschrijvingen heeft gemaakt of null als de inschrijving is gemaakt via de Course Enrollments API of Learning Path Enrollments API.
• groepen (lijst met objecten) - Een lijst van groepsobjecten die zijn ingeschreven (mag leeg zijn).
• gebruikers (lijst met objecten) - Een lijst met gebruikersobjecten die zijn ingeschreven (kan leeg zijn).

{
  "id": "example-enrollments-created-event-id",
  "type": "enrollments.created",
  "createdAt": "2020-09-16T19:59:55.912Z",
  "data": {
    "course": {
      "authorUrl": "<https://api.reach360.com/users/example-author-id>",
      "coverImageUrl": null,
      "id": "example-course-id",
      "courseReportUrl": "<https://api.reach360.com/reports/courses/example-course-id>",
      "title": "Example Course",
      "url": "<https://api.reach360.com/courses/example-course-id>"
	  "source": "rise" 
    },
    "enrolledBy": {
      "email": "admin@example.com",
      "firstName": "Example",
      "groupsUrl": "<https://api.reach360.com/users/example-admin-id/groups>",
      "id": "example-admin-id",
      "lastName": "Admin",
			"lastActiveAt": "2021-10-28T20:39:52.659Z",
      "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-admin-id>",
      "role": "admin",
      "url": "<https://api.reach360.com/users/example-admin-id>"
„Articulate360User”: false „Articulate360User”: false 
    },
    "groups": [],
    "learningPath": null,
    "users": [
      {
        "email": "learner1@example.com",
        "firstName": "Foo",
        "groupsUrl": "<https://api.reach360.com/users/example-learner-1/groups>",
        "id": "example-learner-1",
        "lastName": "Learner",
				"lastActiveAt": "2021-10-28T20:39:52.659Z",
        "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-learner-1>",
        "role": "learner",
        "url": "<https://api.reach360.com/users/example-learner-1>"
 „Articulate360User”: false 
      },
      {
        "email": "learner2@example.com",
        "firstName": "Bar",
        "groupsUrl": "<https://api.reach360.com/users/example-learner-2/groups>",
        "id": "example-learner-2",
        "lastName": "Learner",
				"lastActiveAt": "2021-10-28T20:39:52.659Z",
        "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-learner-2>",
        "role": "learner",
        "url": "<https://api.reach360.com/users/example-learner-2>"
 „Articulate360User”: false 2023-04-04   
      },
		{
        "email": "learner3@example.com",
        "firstName": "Baz",
        "groupsUrl": "<https://api.reach360.com/users/example-learner-3/groups>",
        "id": "example-learner-3",
        "lastName": "Learner",
				"lastActiveAt": "2021-10-28T20:39:52.659Z",
        "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-learner-3>",
        "role": "learner",
        "url": "<https://api.reach360.com/users/example-learner-3>"
   
      },
    ]
  },
  "apiVersion": " ",
  "webhookId": "example-webhook-id"
}

user.created

Opmerking: user.created evenementen worden voor SSO-gebruikers met 5-10 minuten uitgesteld.

Opmerking: user.created gebeurtenissen worden NIET geactiveerd voor SAML-gebruikers die uit uw IDP worden verwijderd en opnieuw worden toegevoegd, tenzij ze ook uit uw Reach-account worden verwijderd.

Wordt geactiveerd wanneer een gebruiker wordt toegevoegd aan uw Reach 360-account.

{
  "id": "example-user-created-event-id",
  "createdAt": "2020-08-24T01:36:18.982Z",
  "type": "user.created",
  "webhookId": "example-webhook-id",
  "apiVersion": "2023-04-04 ",
  "data": {
    "user": {
      "email": "foo@example.com",
      "firstName": "Example First Name",
      "groupsUrl": "<https://api.reach360.com/users/example-user-id/groups>",
      "id": "example-user-id",
      "lastName": "Example Last Name",
			"lastActiveAt": "2021-10-28T20:39:52.659Z",
      "learnerReportUrl": "<https://api.reach360.com/reports/learners/example-user-id>",
      "role": "learner",
      "url": "<https://api.reach360.com/users/example-user-id>"
      "articulate360User": false  
 
    }
  }
}

Verzoeken verifiëren

Wanneer een webhook wordt gemaakt met eensharedSecret, zal Reach 360 in elk verzoek een X-Hook-Signature koptekst bevatten, zodat u kunt verifiëren dat deze afkomstig is van Reach. Om de handtekening te berekenen, gebruikt Reach een HMAC-SHA1 hex-samenvatting met de sharedSecret  en de hoofdtekst van het verzoek.

Hier is een voorbeeld van hoe de verificatiecode voor handtekeningen eruit zou kunnen zien als je Node.js gebruikt (Opmerking: de details kunnen verschillen afhankelijk van het framework dat je gebruikt, de versie van Node die je gebruikt en andere factoren)

const crypto = require('crypto')

const signatureDigest = crypto.createHmac('sha1', process.env.WEBHOOK_SHARED_SECRET)
  .update(Buffer.from(JSON.stringify(request.body)))
  .digest('hex')

if (request.headers['x-hook-signature'] === signatureDigest) {
  // OK: request came from Reach
} else {
  // Error: request didn't come from Reach
}

Foutafhandeling en nieuwe pogingen

Reach 360 stuurt een POST-aanvraag met JSON-gegevens naar de geconfigureerde persoon targetUrl telkens wanneer een van de geconfigureerde gegevens events plaatsvindt. Uw server bevestigt dat hij de payload heeft ontvangen door een antwoord van 200 terug te sturen. Elke reactie buiten het bereik van 200 duidt op een fout. In dat geval zal Reach 360 de aanvraag in de komende 48 uur nog 14 keer proberen te verzenden.