Was dieser API-Endpunkt macht

Webhook-Ereignisse senden Informationen über den Abschluss eines Kurses, die Einreichung des Kurses zur Veröffentlichung, die Registrierung von Benutzern und Gruppen für Kurse und Lernpfade oder wenn ein Benutzer zu Ihrem Reach 360-Konto hinzugefügt wird. Benutzer konfigurieren die Webhooks-API, um die durch diese Ereignisse gesammelten Informationen abzurufen.

Arten von Ereignissen

• course.completed— Wird ausgelöst, wenn ein Lernender einen Kurs abschließt.
• course.submitted— Wird ausgelöst, wenn ein Autor einen Kurs zur Veröffentlichung zur Überprüfung durch einen Administrator einreicht.
• enrollments.created- Wird ausgelöst, wenn Benutzer oder Gruppen entweder für einen Kurs oder einen Lernpfad angemeldet sind.
• user.created- Wird ausgelöst, wenn ein Benutzer zu Ihrem Reach 360-Konto hinzugefügt wird.

Nutzlast für Webhook-Ereignisse

Die Nutzdaten jeder Webhook-Anfrage haben eine gemeinsame Struktur, die von allen Webhook-Ereignissen gemeinsam genutzt wird. Der Hauptteil der Anfrage enthält die folgenden Eigenschaften:

• id(string) — die eindeutige Kennung des Ereignisses
• createdAt(string) — der Zeitpunkt, zu dem das Ereignis eingetreten ist
• type(string) — der Webhook-Ereignistyp
• webhookId(string) — die ID des Webhooks, der zum Senden des Ereignisses geführt hat
• apiVersion(string) — API-Version, die beim Senden des Webhook-Ereignisses verwendet wurde. Wird auch als API-Version Header in der Anfrage gesendet
• data(Objekt) — spezifisch für den Typ des Webhook-Ereignistyps (siehe Beispiele)

Payload-Beispiele anfordern

Jedes Beispiel für ein Webhook-Ereignis unten zeigt ein Beispiel dafür, wie eine Webhook-Anfrage an die Ziel-URL auf Ihrem Server aussehen würde.

course.completed

Wird ausgelöst, wenn ein Lernender einen Kurs abschließt.

Eigenschaften der Nutzdaten von Ereignissen:

• Kurs (Objekt) — das Kursobjekt für den entsprechenden Kurs oder null, wenn die Anmeldungen für einen Lernpfad sind. Dieses Kursobjekt hat auch ein Quizobjekt mit zwei Eigenschaften: bestanden und Punktzahl. Wenn dem Kurs kein Quiz zugeordnet ist, ist das Objekt leer.

• user (object) — das Benutzerobjekt für den zugehörigen Benutzer.

{
„id“: „Beispiel-Kurs-abgeschlossene-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“: 
 „Beispiel-Kurs-ID“, 
 „courseReportUrl“: "https://api.reach360.com/reports/courses/example-course-id 
 „, „title“: „Beispielkurs“, 
 „url“:“ 
 
 
 https://api.reach360.com/courses/example-course-id „, 
 „contentType“: „RISE“ 
 „quiz“: {„bestanden“: true, 
 „score“: 80
}
}, 
 „user“: {
„email“: "foo@example.com „, „firstName“: „Beispiel Vorname“, „groupsURL“: "https://api.reach360.com/users/example-user-id/groups „, „id“: 
 „example-user-id“, „lastName“: 
 „Beispiel für einen Nachnamen“, „lastActiveAt“: 
 „2021-2021 10-28T 20:39:52.659 Z“, 
 „URL des Teilnehmerberichts“: "https://api.reach360.com/reports/learners/example-user-id „, 
 
„Rolle“: „Lernender“, 
 „url“: "https://api.reach360.com/users/example-user-id „, 
 „articulate360User“: falsch
}
}
}

course.submitted

Wird ausgelöst, wenn ein Autor einen Kurs zur Überprüfung durch einen Administrator zur Veröffentlichung einreicht.

{
  "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“: falsch „Articulate360User“: falsch 
    },
    "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

Wird ausgelöst, wenn Benutzer oder Gruppen entweder für einen Kurs oder einen Lernpfad angemeldet sind.

Die Payload dieses Ereignisses enthält immer dieselben Eigenschaftsnamen, aber welche dieser Eigenschaften Werte haben, hängt von der Art der erstellten Anmeldungen ab.

Wenn beispielsweise ein oder mehrere Benutzer für einen Kurs angemeldet sind, enthält der data Teil der Payload, der an Ihren Handler gesendet wird, eine users Array-Eigenschaft (ein Array von Benutzerobjekten) und eine Eigenschaft. course In diesem Szenario ist die groups Eigenschaft ein leeres Array und learningPath wird auf gesetzt. null

Ähnlich verhält es sich, wenn eine oder mehrere Gruppen für einen Lernpfad angemeldet sind, das data Objekt über eine groups Array-Eigenschaft (ein Array von Gruppenobjekten) und eine learningPath Eigenschaft, während users es ein leeres Array ist und es auch sein course null wird.

Eigenschaften der Nutzdaten von Ereignissen:

• Kurs (Objekt) — das Kursobjekt für den entsprechenden Kurs oder null wenn die Anmeldungen für einen Lernpfad sind.
• learningPath (Objekt) — das Lernpfadobjekt für den zugehörigen Lernpfad oder null wenn die Anmeldungen für einen Kurs sind.
• enrolledBy (Objekt) — Das Benutzerobjekt des Benutzers, der die Anmeldungen erstellt hat, oder null wenn die Anmeldung über die Course Enrollments API oder Learning Path Enrollments API erstellt wurde.
• groups (Objektliste) — Eine Liste von Gruppenobjekten, die registriert wurden (kann leer sein).
• Benutzer (Objektliste) — Eine Liste von Benutzerobjekten, die registriert wurden (kann leer sein).

{
  "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“: falsch „Articulate360User“: falsch 
    },
    "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“: falsch 
      },
      {
        "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“: falsch 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

Hinweis: user.created Ereignisse werden für SSO-Benutzer um 5-10 Minuten verzögert.

Hinweis: user.created Ereignisse werden NICHT für SAML-Benutzer ausgelöst, die aus Ihrem IDP entfernt und erneut hinzugefügt wurden, es sei denn, sie werden auch aus Ihrem Reach-Konto entfernt.

Wird ausgelöst, wenn ein Benutzer zu Ihrem Reach 360-Konto hinzugefügt wird.

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

Anfragen werden überprüft

Wenn ein Webhook mit einem erstellt wirdsharedSecret, fügt Reach 360 jeder Anfrage einen X-Hook-Signature Header hinzu, sodass Sie überprüfen können, ob sie von Reach stammt. Um die Signatur zu berechnen, verwendet Reach einen HMAC-SHA1-Hex-Digest mit dem sharedSecret  und dem Hauptteil der Anfrage.

Hier ist ein Beispiel dafür, wie der Signaturbestätigungscode aussehen könnte, wenn Sie Node.js verwenden (Hinweis: Die Einzelheiten können je nach verwendetem Framework, der Version von Node, auf der Sie sich befinden, und anderen Faktoren unterschiedlich sein)

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
}

Fehlerbehandlung und Wiederholungsversuche

Reach 360 sendet targetUrl jedes Mal, wenn eine der konfigurierten Anfragen events auftritt, eine POST-Anfrage mit JSON-Daten an die konfigurierte Datei. Ihr Server bestätigt, dass er die Payload empfangen hat, indem er eine 200-Antwort zurücksendet. Jede Antwort außerhalb des Bereichs 200 weist auf einen Fehler hin. In diesem Fall wird Reach 360 in den nächsten 48 Stunden erneut versuchen, die Anfrage 14 Mal zu senden.