Skip to content

AcademIA Webhook

AcademIA Webhook is a starting component: it runs the flow every time AcademIA reports a learning event, for example that someone finishes a lesson, passes or fails a quiz, completes a course or earns a certificate. Each event is one run of the flow.

AcademIA sends its activity in the standard e-learning format, xAPI, to what it calls an LRS (Learning Record Store, the record where learning activity is kept). This component acts as the LRS for your flow: it receives each event and turns it into simple data, such as who it was, which course or lesson, the score and the date.

When to use it

  • Congratulate by email every learner who completes a course.
  • Notify the manager when someone fails a quiz.
  • Record the certificates issued in your CRM or your HR system.
  • Keep your team’s training progress in a spreadsheet.

Configuration

AcademIA is the one that calls the flow. For the component to check that calls come from AcademIA, create an AcademIA xAPI credential with a Shared secret: a long random value you choose and that only the flow and AcademIA will know. See Credentials.

FieldWhat it does
EventsThe events that start the flow. The rest are ignored. By default, all of them are ticked.
CredentialOptional, but recommended. The AcademIA xAPI credential with the shared secret (Shared secret). With it, any call that doesn’t carry that secret is rejected. Without a credential, it isn’t checked.
Skip repeated deliveries (advanced)On by default. AcademIA sends an event again when the answer is late; this way the same fact runs the flow only once.
Run on test statements (advanced)Off by default. AcademIA’s Test connection button sends a test enrollment: it is accepted, but it doesn’t run the flow unless you turn this on.
DataUsed to test the component in the editor: paste a sample event here and run the flow. When the flow runs through its webhook, it is filled with what was received. Leave it empty.

These are the events and what they are called in AcademIA:

Event in EventsWhat happenedIn AcademIA, under Events to send
EnrollmentSomeone enrolled in a course.Enrolled in a course
Lesson CompletedSomeone finished a lesson.Lesson completed
Quiz PassedSomeone passed a quiz.Quiz graded
Quiz FailedSomeone failed a quiz.Quiz graded
Game CompletedSomeone completed a game activity.Game activity completed
Path CompletedSomeone completed a course (a learning path).Course completed
Certificate IssuedAcademIA issued a certificate.Certificate issued

Set it up in AcademIA

  1. Create the AcademIA xAPI credential with a long random value in Shared secret and choose it in the component’s Credential field.
  2. Deploy a version of the flow: calls to the webhook run the deployed version. See Versions and publishing.
  3. Open the API Access window, go to the Webhook tab, choose the API Key and copy the address. It looks like this: <NappAI API address>/api/v1/webhook/<flow id>?x-api-key=<API key>. The key goes inside the address because AcademIA can’t add headers to what it sends. See API keys.
  4. Sign in to AcademIA as a Corporate admin (CORPORATE_ADMIN) of your organisation. In the menu, under the Advanced section, open LRS (xAPI). This integration needs AcademIA’s ENTERPRISE plan.
  5. In xAPI endpoint, paste the flow’s address.
  6. Leave User (Basic Auth) empty and type in Credential the word Bearer, a space and the same value you saved in the Shared secret of the AcademIA xAPI credential. For example, if the secret is k8Qz…, type Bearer k8Qz….
  7. Under Events to send, tick the same events as in Events. If you want to receive each person’s name and email, turn on Include the learner’s real name and email.
  8. Click Save and then Test connection. AcademIA sends a test enrollment and tells you whether it was accepted.

An AcademIA Super admin can do the same in the Platform LRS, which collects the activity of users who don’t belong to any organisation.

Output

The Data output delivers the event with this data:

  • event: the event, for example Quiz Failed.
  • user_id: the person’s ID in AcademIA.
  • email and name: the person’s email and name. They only arrive if Include the learner’s real name and email is on in AcademIA.
  • activity_type (course, lesson, assessment or interaction), activity_id and activity_name: the course, lesson, quiz or game.
  • score (from 0 to 100), success (whether they passed) and completion (whether they finished it).
  • game_type and xp_earned for games.
  • certificate_url and certificate_hash for issued certificates.
  • timestamp: when it happened.
  • statement: the whole event, as AcademIA sent it.

If an event arrives that isn’t ticked in Events, a test event or a repeated delivery, the flow stops at this component without an error.

Example

A company wants to send the diploma to every employee who finishes a course.

  1. Add AcademIA Webhook, choose its AcademIA xAPI credential and leave only Certificate Issued ticked in Events.
  2. Connect Data to AcademIA Certificates with the Verify Certificate operation and, in Certificate, the event’s certificate_hash. To check a certificate by its code, the key of the AcademIA credential must act as a Content admin or a Super admin.
  3. Connect the result to an agent that writes the congratulations and to Gmail Message to send it to the person’s email with the certificate_url link.
  4. Deploy the flow and set it up in AcademIA as the organisation’s LRS, with the Certificate issued event and Include the learner’s real name and email turned on.

Good practices

  • Always use an AcademIA xAPI credential. Without it, anyone who has the flow’s address can start it.
  • Tick the same events in AcademIA and in Events: what AcademIA doesn’t send never arrives, and what it sends in excess only uses up runs that are discarded.
  • If you don’t turn on the email in AcademIA, identify the person by user_id and read their details with AcademIA Organization, Get Member operation.
  • A flow can only have one webhook component.

Security and limitations

  • AcademIA doesn’t sign what it sends: the protection is the secret in the AcademIA xAPI credential and the API key in the address. If you change the secret, change it in the credential and in AcademIA at the same time. Don’t share the flow’s address.
  • AcademIA only sends the Enrollment event when the person enrolls on their own. Enrollments made by a company when assigning a course, or those that come from an invitation, don’t generate it.
  • The name and the email are personal data that AcademIA hands over to the flow. Turn them on only if your contract and your privacy notice cover it.
  • When you test by pasting an event into Data, the secret isn’t checked: it is only checked on real calls.