Cosa fa questo endpoint API

Gli eventi Webhook inviano informazioni sul completamento del corso, sull'invio del corso per la pubblicazione, sull'iscrizione di utenti e gruppi a corsi e percorsi di apprendimento o sull'aggiunta di un utente all'account Reach 360. Gli utenti configurano l'API Webhooks per recuperare le informazioni raccolte da questi eventi.

Tipi di eventi

• course.completed- Attivato quando un allievo completa un corso.
• course.submitted- Attivato quando un autore invia un corso per essere esaminato da un amministratore per la pubblicazione.
• enrollments.created- Attivato quando utenti o gruppi sono iscritti a un corso o a un percorso di apprendimento.
• user.created- Attivato quando un utente viene aggiunto al tuo account Reach 360.

- Payload degli eventi Webhook

Il payload di ogni richiesta webhook ha una struttura comune condivisa da tutti gli eventi webhook. Il corpo della richiesta contiene le seguenti proprietà:

• id(string) - l'identificatore univoco dell'evento
• createdAt(stringa) - l'ora in cui si è verificato l'evento
• type(string) - il tipo di evento webhook
• webhookId(string) - l'id del webhook che ha portato all'invio dell'evento
• apiVersion(string) - Versione API utilizzata per l'invio dell'evento webhook. Verrà inviata anche come API-Version intestazione nella richiesta
• data(oggetto) - specifico per il tipo di tipo di evento webhook (vedi esempi)

Richiedi esempi di payload

Ogni esempio di evento webhook riportato di seguito mostra un esempio di come sarebbe una richiesta webhook all'URL di destinazione sul server.

course.completed

Attivato quando un allievo completa un corso.

Proprietà dei dati del payload dell'evento:

• course (object) - l'oggetto del corso per il corso correlato o nullo se le iscrizioni riguardano un percorso di apprendimento. Questo oggetto del corso ha anche un oggetto quiz a scelta multipla con due proprietà: pass e punteggio. Se non ci sono quiz a scelta multipla associati al corso, l'oggetto sarà vuoto.

• user (object) - l'oggetto utente per l'utente correlato.

{
«id»: «example-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»: {«corso»: {«corso»: {«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»: 
 «Corso di esempio», «url»:
» 
 
 
 
 
 https://api.reach360.com/courses/example-course-id «, 
 «contentType»: «RISE» 
 «quiz a scelta multipla»
: {«passed»: 
 true, «score»: 
 80}
}, «user»
: {«email»: "foo@example.com «, «firstName»: «Nome di esempio», «groupSURL»: "https://api.reach360.com/users/example-user-id/groups «, «id
»: «example-user-id», «lastName»: 
 «Esempio di cognome», lastActiveAT
»: «28/10/2021 T 20:39:52.659 Z
», «learnerReportURL»: "https://api.reach360.com/reports/learners/example-user-id «, 
 
«role»: «allievo», «url»: "https://api.reach360.com/users/example-user-id 
 «, 
 «articulate360User»: false}}} 
 
 

course.submitted

Attivato quando un autore invia un corso per essere esaminato da un amministratore per la pubblicazione.

{
  "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

Attivato quando utenti o gruppi sono iscritti a un corso o a un percorso di apprendimento.

Il payload di questo evento contiene sempre gli stessi nomi di proprietà, ma le proprietà con valori variano a seconda del tipo di iscrizioni create.

Ad esempio, se uno o più utenti sono iscritti a un corso, la data parte del payload inviata al gestore includerà una proprietà users array (una matrice di oggetti utente) e una proprietà. course In questo scenario la groups proprietà sarà una matrice vuota e learningPath verrà impostata su. null

Allo stesso modo, se uno o più gruppi sono iscritti in un percorso di apprendimento, l'dataoggetto avrà una proprietà groups array (un array di Group Objects) e una learningPath proprietà, mentre users sarà un array vuoto e course lo sarànull.

Proprietà dei dati del payload dell'evento:

• course (object) - l'oggetto del corso per il corso correlato o null se le iscrizioni riguardano un percorso di apprendimento.
• learningPath (object) - l'oggetto del percorso di apprendimento per il relativo percorso di apprendimento o null se le iscrizioni sono per un corso.
• enrolledBy (object) - L'oggetto utente dell'utente che ha creato le iscrizioni o se l'iscrizione è stata creata tramite l'API null Course Enrollments o l'API Learning Path Enrollments.
• groups (elenco di oggetti) - Un elenco di oggetti di gruppo che sono stati registrati (può essere vuoto).
• users (elenco di oggetti) - Un elenco di oggetti utente che sono stati registrati (può essere vuoto).

{
  "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 «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>"
 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

Nota: gli user.created eventi verranno ritardati per gli utenti SSO di 5-10 minuti.

Nota: user.created gli eventi NON vengono attivati per gli utenti SAML che vengono rimossi dal tuo IDP e aggiunti nuovamente, a meno che non vengano rimossi anche dal tuo account Reach.

Attivato quando un utente viene aggiunto al tuo account Reach 360.

{
  "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  
 
    }
  }
}

Verifica delle richieste

Quando un webhook viene creato con unsharedSecret, Reach 360 includerà un'X-Hook-Signatureintestazione in ogni richiesta, consentendoti di verificare che provenga da Reach. Per calcolare la firma, Reach utilizza un digest esadecimale HMAC-SHA1 con il e il corpo della sharedSecret  richiesta.

Ecco un esempio di come potrebbe apparire il codice di verifica della firma se utilizzi Node.js (nota: le specifiche possono variare a seconda del framework che stai utilizzando, della versione di Node in uso e di altri fattori)

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
}

Gestione degli errori e nuovi tentativi

Reach 360 invierà una richiesta POST con dati JSON al configurato targetUrl ogni volta che events si verifica uno dei configurati. Il server riconosce di aver ricevuto il payload inviando una risposta di 200. Qualsiasi risposta al di fuori dell'intervallo 200 indica un errore. In tal caso, Reach 360 riproverà a inviare la richiesta altre 14 volte nelle prossime 48 ore.