Het supportteam van aNewSpring kan webhooks instellen, zodat ze een POST request naar de URL van een extern systeem versturen. Deze webhooks bevatten gegevens over de deelnemer en de resultaten van een uitvoering (cursus) of activiteit. (Hieronder staan voorbeelden.)

Ben je geen ontwikkelaar? Er is ook een artikel met een eenvoudigere uitleg.

Het formaat van de berichten kan of JSON (application/json) of XML (text/xml) zijn. De codering is UTF-8.

Om te bepalen of een bericht daadwerkelijk afkomstig is van aNewSpring is het mogelijk om een secret te configureren. Alle berichten bevatten dan een X-WebHook-Signature header met een Base64 gecodeerde HMAC-SHA1 van het bericht en de secret.

Een omgevingsbeheerder van de leeromgeving kan via support@anewspring.com een verzoek doen om de webhooks in te stellen.
We hebben daarvoor de volgende informatie nodig:
  • De URL waar webhooks naar gestuurd moeten worden.
  • Je voorkeur voor het formaat van het bericht (JSON of XML).
  • Een secret code, als je wilt dat wij de X-WebHook-Signature header sturen.
  • Of je een "pretty" versie van het bericht wilt ontvangen, zodat het bericht voor mensenogen makkelijker te lezen is.

Als de URL waar we het bericht naar sturen niet binnen 10 seconden een respons geeft OF als we geen status 200, 201, 202 of 204 terugkrijgen, proberen we het bericht nog 10 keer af te leveren met een oplopende interval (van 10 seconden tot 16 uur).

Het is belangrijk dat wij alleen een nuttige foutcode ontvangen waardoor we nog een poging zullen doen om het bericht te versturen, dus bijvoorbeeld bij een tijdelijke error.

Je hoeft geen foutcode te versturen als bijvoorbeeld de gebruiker of cursus in het externe systeem niet bestaat of als een bepaald type webhook niet wordt ondersteund.

Elk bericht bevat een veld dat aangeeft welke webhook was getriggerd. Dit veld heeft de naam event in een JSON bericht en type in een XML bericht. Hieronder vind je een overzicht van de mogelijke webhooks.
Elk bericht bevat ook een veld created en daarin staat de datum waarop de webhook oorspronkelijk was gemaakt. Als we een nieuwe poging doen om het bericht te versturen (omdat het niet kon worden bezorgd of omdat we een foutcode terug kregen), blijft deze datum hetzelfde.

Overzicht van webhooks

Dit zijn de webhooks die we op dit moment versturen. Wij kunnen niet instellen welke webhooks wel of niet kunnen worden verzonden, dus ze worden allemaal verzonden. Het is aan het externe systeem om te bepalen of het bericht relevant is.

CourseActivated

Deze webhook wordt verstuurd wanneer een deelnemer aan een cursus begint (of wanneer een beheerder handmatig de status van de inschrijving verandert van nieuw naar actief).

Voorbeeld van een JSON-bericht:

{
  "created": "2014-09-01T12:00:00.000Z",
  "event": "CourseActivated",
  "id": "5db1cc3b-4306-4689-91e4-def0bff0e58d",
  "user": {
    "course": {
      "id": "prince2",
      "name": "Prince 2",
      "uid": "a62b0836-7682-11eb-b67e-06575dd7e8c5"
    },
    "id": "jwatson",
    "name": "John Watson",
    "uid": "c21f7c68-7682-11eb-b67e-06575dd7e8c5"
  }
}

Voorbeeld van een XML-bericht:

<event id="5db1cc3b-4306-4689-91e4-def0bff0e58d" type="CourseActivated" created="2014-09-01T12:00:00.000Z">
  <user id="jwatson" uid="c21f7c68-7682-11eb-b67e-06575dd7e8c5" name="John Watson">
    <course id="prince2" uid="a62b0836-7682-11eb-b67e-06575dd7e8c5" name="Prince 2"/>
  </user>
</event>

CoursePartCompleted

Deze webhook wordt verzonden nadat een deelnemer een activiteit afrondt (MemoTrainingen en extra oefeningen vallen hier niet onder).

Voorbeeld van een JSON-bericht:

{
  "created": "2014-09-01T12:00:00.000Z",
  "event": "CoursePartCompleted",
  "id": "31500949-6420-468d-91e4-def0bff0e58d",
  "user": {
    "course": {
      "id": "prince2",
      "name": "Prince 2",
      "part": {
        "attempt": {
          "attemptNr": -1,
          "completeDate": "2014-09-01",
          "completeDateTime": "2014-09-01T13:25:03Z",
          "completed": true,
          "passed": true,
          "progress": "2/2",
          "score": "10.0",
          "startDate": "2014-09-01",
          "startDateTime": "2014-09-01T13:20:41Z",
          "terms": [{
            "maxScore": 3,
            "name": "Term 1",
            "score": 1,
            "threshold": 2
          }]
        },
        "id": "assessment1",
        "name": "Assessment 1",
        "type": "Assessment",
        "uid": "1807abf8-f34b-404d-8bb3-d6b8fd5ffb27"
      },
      "uid": "a62b0836-7682-11eb-b67e-06575dd7e8c5"
    },
    "id": "jwatson",
    "name": "John Watson",
    "uid": "c21f7c68-7682-11eb-b67e-06575dd7e8c5"
  }
}

Voorbeeld van een XML-bericht:

<event id="31500949-6420-468d-91e4-def0bff0e58d" type="CoursePartCompleted" created="2014-09-01T12:00:00.000Z">
  <user id="jwatson" uid="c21f7c68-7682-11eb-b67e-06575dd7e8c5" name="John Watson">
    <course id="prince2" uid="a62b0836-7682-11eb-b67e-06575dd7e8c5" name="Prince 2">
      <part id="assessment1" uid="1807abf8-f34b-404d-8bb3-d6b8fd5ffb27" name="Assessment 1" type="Assessment">
        <attempt attemptNr="-1">
          <startDate>2014-09-01</startDate>
          <startDateTime>2014-09-01T13:20:41Z</startDateTime>
          <completed>true</completed>
          <completeDate>2014-09-01</completeDate>
          <completeDateTime>2014-09-01T13:25:03Z</completeDateTime>
          <progress>2/2</progress>
          <score>10.0</score>
          <passed>true</passed>
          <terms>
            <term name="Term 1">
              <maxScore>3</maxScore>
              <score>1</score>
              <threshold>2</threshold>
            </term>
          </terms>
          <criteria/>
        </attempt>
      </part>
    </course>
  </user>
</event>

CourseCompleted

Deze webhook wordt verzonden nadat een deelnemer een activiteit afrondt die is geselecteerd als Cursus afsluitende activiteit in de template-instellingen.

De parameter grade bevat de score van de activiteit die is geselecteerd bij Cursus eindcijfer baseren op.
De parameter passed bevat true of false als de activiteit die is geselecteerd bij Cursus eindcijfer baseren op een slagingsgrens heeft. Anders bevat deze null.
De activiteit die bij Cursus eindcijfer baseren op is geselecteerd moet afgerond worden voordat de Cursus afsluitende activiteit is afgerond, of je kan dezelfde activiteit bij beide instellingen selecteren.

Let op: Op het moment dat deze webhook wordt verstuurd, wordt er op hetzelfde moment ook een webhook CoursePartCompleted verstuurd met gedeeltelijk dezelfde informatie. In de webhook wordt aangegeven of het om CourseCompleted of CoursePartCompleted gaat.

Voorbeeld van een JSON-bericht:

{
  "created": "2014-09-01T12:00:00.000Z",
  "event": "CourseCompleted",
  "id": "5db1cc3b-4306-4689-9eae-971c205c2c10",
  "user": {
    "course": {
      "id": "prince2",
      "name": "Prince 2",
      "grade": "10.0",
      "passed": true,
      "uid": "a62b0836-7682-11eb-b67e-06575dd7e8c5"
    },
    "id": "jwatson",
    "name": "John Watson",
    "uid": "c21f7c68-7682-11eb-b67e-06575dd7e8c5"
  }
}

Voorbeeld van een XML-bericht:

<event id="5db1cc3b-4306-4689-9eae-971c205c2c10" type="CourseCompleted" created="2014-09-01T12:00:00.000Z">
  <user id="jwatson" uid="c21f7c68-7682-11eb-b67e-06575dd7e8c5" name="John Watson">
    <course id="prince2" uid="a62b0836-7682-11eb-b67e-06575dd7e8c5" name="Prince 2">
      <grade>10.0</grade>
      <passed>true</passed>
    </course>
  </user>
</event>

CourseAdded

Deze webhook wordt verstuurd wanneer een deelnemer wordt ingeschreven voor een uitvoering.

Voorbeeld van een JSON-bericht:

{
  "created": "2014-09-01T12:00:00.000Z",
  "event": "CourseAdded",
  "id": "5db1cc3b-4306-4689-91e4-def0bff0e58d",
  "user": {
    "course": {
      "id": "prince2",
      "name": "Prince 2",
      "uid": "a62b0836-7682-11eb-b67e-06575dd7e8c5"
    },
    "id": "jwatson",
    "name": "John Watson",
    "uid": "c21f7c68-7682-11eb-b67e-06575dd7e8c5"
  }
}

Voorbeeld van een XML-bericht:

<event id="5db1cc3b-4306-4689-91e4-def0bff0e58d" type="CourseAdded" created="2014-09-01T12:00:00.000Z">
  <user id="jwatson" uid="c21f7c68-7682-11eb-b67e-06575dd7e8c5" name="John Watson">
    <course id="prince2" uid="a62b0836-7682-11eb-b67e-06575dd7e8c5" name="Prince 2"/>
  </user>
</event>

CourseDeleted

Deze webhook wordt verzonden wanneer een inschrijving van een deelnemer wordt verwijderd.

Voorbeeld van een JSON-bericht:

{
  "created": "2014-09-01T12:00:00.000Z",
  "event": "CourseDeleted",
  "id": "5db1cc3b-4306-4689-91e4-def0bff0e58d",
  "user": {
    "course": {
      "id": "prince2",
      "name": "Prince 2",
      "uid": "a62b0836-7682-11eb-b67e-06575dd7e8c5"
    },
    "id": "jwatson",
    "name": "John Watson",
    "uid": "c21f7c68-7682-11eb-b67e-06575dd7e8c5"
  }
}

Voorbeeld van een XML-bericht:

<event id="5db1cc3b-4306-4689-91e4-def0bff0e58d" type="CourseDeleted" created="2014-09-01T12:00:00.000Z">
  <user id="jwatson" uid="c21f7c68-7682-11eb-b67e-06575dd7e8c5" name="John Watson">
    <course id="prince2" uid="a62b0836-7682-11eb-b67e-06575dd7e8c5" name="Prince 2"/>
  </user>
</event>

EventSubscribed

Deze webhook wordt verzonden wanneer een deelnemer op een event wordt ingeschreven.

Voorbeeld van een JSON-bericht:

{
  "created": "2014-09-01T12:00:00.000Z",
  "event": "EventSubscribed",
  "id": "5db1cc3b-4306-4689-91e4-def0bff0e58d",
  "user": {
    "bookableEvent": {
      "id": "prince2",
      "name": "Prince 2",
    },
    "id": "jwatson",
    "name": "John Watson",
    "uid": "c21f7c68-7682-11eb-b67e-06575dd7e8c5"
  }
}

Voorbeeld van een JSON-bericht:

<event id="5db1cc3b-4306-4689-91e4-def0bff0e58d" type="EventSubscribed" created="2014-09-01T12:00:00.000Z">
  <user id="jwatson" uid="c21f7c68-7682-11eb-b67e-06575dd7e8c5" name="John Watson">
    <bookableEvent id="prince2" name="Prince 2"/>
  </user>
</event>

EventUnsubscribed

Deze webhook wordt verzonden wanneer een deelnemer voor een event wordt uitgeschreven.

Example of a JSON message:

{
  "created": "2014-09-01T12:00:00.000Z",
  "event": "EventUnsubscribed",
  "id": "5db1cc3b-4306-4689-91e4-def0bff0e58d",
  "user": {
    "bookableEvent": {
      "id": "prince2",
      "name": "Prince 2",
    },
    "id": "jwatson",
    "name": "John Watson",
    "uid": "c21f7c68-7682-11eb-b67e-06575dd7e8c5"
  }
}

Voorbeeld van een XML-bericht:

<event id="5db1cc3b-4306-4689-91e4-def0bff0e58d" type="EventUnsubscribed" created="2014-09-01T12:00:00.000Z">
  <user id="jwatson" uid="c21f7c68-7682-11eb-b67e-06575dd7e8c5" name="John Watson">
    <bookableEvent id="prince2" name="Prince 2"/>
  </user>
</event>