Reach 360: Webhook-Ereignisse

Letzte Aktualisierung des Artikels:

Dieser Artikel gilt für:

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 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) — der eindeutige Bezeichner des Ereignisses
createdAt(string) — der Zeitpunkt, zu dem das Ereignis eingetreten ist
type(string) — der Webhook-Ereignistyp
webhookId(string) — die ID des Webhooks, der dazu geführt hat, dass das Ereignis gesendet wurde
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 Payload-Daten 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 Nutzdaten dieses Ereignisses enthalten 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 Ereignis-Payloaddata:

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.rise.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 Rise-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 sharedSecret Rise erstellt wird, enthält jede Anfrage einen X-Hook-Signature Header, 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

Rise sendet targetUrl jedes Mal, wenn eine der konfigurierten Anfragen events auftritt, eine POST-Anfrage mit JSON-Daten an die Konfiguration. 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 Rise in den nächsten 48 Stunden erneut versuchen, die Anfrage 14 Mal zu senden.

Vorgestellte Bücher

Vorgestellte Ressourcen

Erstellung von Kursen

Browse Articles