HowToo offers a seamless Academy service, covering learner provisioning, course management, and learning delivery through an integration service that embeds directly into any site.
Key features
- Learner management: The learner management API allows the integrated system to add, retrieve, activate, and deactivate learner accounts within HowToo Academy.
- Course management: The course management API allows the integrated system to track course information and monitor learner progress.
- Webhook: This enables external systems to listen for real-time events related to user activity and course updates in HowToo Academy.
- Embedded Academy via iFrame: This allows HowToo Academy courses to be embedded directly into external websites or applications using an iFrame. This enables learners to access and complete courses without leaving the host platform.
Learner management API
The learner management APIs enable the integrated system to add, retrieve, activate, and deactivate the learner account in HowToo Aacademy.
Add learner endpoint
API doc: https://howtoo.stoplight.io/docs/howtoo-api/branches/main/ed07tx97ca7ih-create-learner-endpoint
Request format:
POST /v1/learners HTTP/1.1
Host: api.howtoo.co
x-api-key: <API_KEY>
Content-Type: application/json
{
"email": "user@example.com",
"fullname": "full name",
}
Response:
{
“message”: “Learner created successfully”,
“data”: {
“learnerId”: 123456789
}
}
Retrieve learner endpoint
Request format:
GET /v1/learners/123456789 HTTP/1.1
Host: api.howtoo.co
x-api-key: <API_KEY>
Content-Type: application/json
Response:
{
“message”: “Learner retrieved successfully”,
“data”: {
“learnerId”: 123456789,
“email”: “example@example.com”,
“fullname”: “”
“status”: “active”
}
}
Activate/deactivate endpoint
API doc: https://howtoo.stoplight.io/docs/howtoo-api/ocg2y0qc9njyb-update-learner-account-status-endpoint
Request format:
PUT /v1/learners/123456789 HTTP/1.1
Host: api.howtoo.co
x-api-key: <API_KEY>
Content-Type: application/json
{
"isActive": true,
}
Response:
{
“message”: “Learner activate successfully”
}
Add/remove learners to/from a learner group endpoint
API doc: https://howtoo.stoplight.io/docs/howtoo-api/ydtioy8mzwawr-add-remove-learners-to-from-a-learner-group
Request format:
PUT /v1/learners/group HTTP/1.1
Host: api.howtoo.co
x-api-key: <API_KEY>
Content-Type: application/json
{
"learners": [1,2,3],
"groupId": 1,
"action": "add"
}
Response:
{
“message”: “Learner group updated successfully”
}
Course and lesson management API
The course management APIs allow the integrated system to manage courses in the HowToo account.
Search course endpoint
API doc: https://howtoo.stoplight.io/docs/howtoo-api/xmud83if5d0rc-search-courses
Request format:
GET /v1/courses?search=course&page=1&pageSize=20 HTTP/1.1
Host: api.howtoo.co
x-api-key: <API_KEY>
Content-Type: application/json
Response:
{
“message”: “Searched courses successfully”,
“data”: [{
“courseId”: 1,
“courseName”: “course name”,
“courseDescription”: “course description”,
“courseAuthor”: “author full name”,
“courseEnrollmentCount”: 10
}],
“meta”: {
page: 1,
pageSize: 20,
count: 1
}
}
Retrieve course information endpoint
API doc: https://howtoo.stoplight.io/docs/howtoo-api/dei4p7h99lpjx-get-course-information
Request format:
GET /v1/courses/1 HTTP/1.1
Host: api.howtoo.co
x-api-key: <API_KEY>
Content-Type: application/json
Response:
{
“message”: “Fetched course info successfully”,
“data”: {
“courseId”: 1,
“courseName”: “course name”,
“courseDescription”: “course description”,
“courseAuthor”: “author full name”,
“courseEnrollmentCount”: 1,
“enrolledLearners”: [{
“learnerId”: 1
“learnerName”: “name”,
“learnerEmail”: “email”,
“completedDate”: “2024-04-03”,
“startDate”: “2024-04-03”,
“score”: 100,
“status”: “complete”,
“recentLaunchedDate”: “2024-04-03”
}]
},
}
Retrieve lesson information endpoint
API doc: https://howtoo.stoplight.io/docs/howtoo-api/branches/main/il4eg2ta5c8me-get-lesson-information
Request format:
GET /v1/lessons/1 HTTP/1.1
Host: api.howtoo.co
x-api-key: <API_KEY>
Content-Type: application/json
Response:
{
“message”: “Fetched lesson info successfully”,
“data”: {
“lessonId”: 1,
“lessonName”: “lesson name”,
“lessonDescription”: “lesson description”,
“lessonEnrollmentCount”: 1,
“enrolledLearners”: [{
“learnerId”: 1
“learnerName”: “name”,
“learnerEmail”: “email”,
“completedDate”: “2024-04-03”,
“startDate”: “2024-04-03”,
“score”: 100,
“status”: “complete”,
}]
},
}
Update course status endpoint
API doc: https://howtoo.stoplight.io/docs/howtoo-api/69d4e8p5mkvxv-update-a-course-status-for-a-learner
Request format:
PUT /v1/learners/1/courses/1 HTTP/1.1
Host: api.howtoo.co
x-api-key: <API_KEY>
Content-Type: application/json
{
"status": "completed",
"toUpdateLessonsStatus": true
}
Response:
{
“message”: “Course status updated successfully”,
“data”: {
“courseId”: 1,
“courseName”: “course name”,
"learnerId": 1,
"learnerName": "",
"learnerEmail": "learner@example.com",
"status": "completed"
},
}
Update lesson status endpoint
API doc: https://howtoo.stoplight.io/docs/howtoo-api/69d4e8p5mkvxv-update-a-course-status-for-a-learner
Request format:
PUT /v1/learners/1/lesson/1 HTTP/1.1
Host: api.howtoo.co
x-api-key: <API_KEY>
Content-Type: application/json
{
"status": "completed",
}
Response:
{
“message”: “Course status updated successfully”,
“data”: {
“lessonId”: 1,
“lessonName”: “course name”,
"learnerId": 1,
"learnerName": "",
"learnerEmail": "learner@example.com",
"status": "completed"
},
}
Enrol learners into a course endpoint
API doc: https://howtoo.stoplight.io/docs/howtoo-api/anqwhzcqinrf7-enroll-learners-into-a-course
Request format:
PUT /v1/courses/1 HTTP/1.1
Host: api.howtoo.co
x-api-key: <API_KEY>
Content-Type: application/json
{
"email": [“example@example.com”],
}
Response:
{
“message”: “enrol the learners to the course successfully”,
“data”: {
“courseId”: 1,
“courseName”: “course name”,
“courseDescription”: “course description”,
“courseAuthor”: “author full name”,
“courseEnrollmentCount”: 1,
“enrolledLearners”: [{
“learnerId”: 1
“learnerName”: “name”,
“learnerEmail”: “email”,
“completedDate”: null,
“startDate”: null,
“score”:null,
“status”: “not started”,
“recentLaunchedDate”: null
}]
},
}
Webhook
HowToo uses webhooks to notify the integrated system when an event happens in your HowToo Academy.
Authentication
To ensure the authenticity and integrity of webhook requests, a signature authentication strategy is employed. This strategy utilizes a shared secret key known only to the webhook provider and the receiver. When a webhook event occurs, the provider generates a signature using a hashing algorithm (HMAC-SHA256) and includes it in the request header - Authorization.
Upon receiving the webhook request, the receiver calculates its own signature using the same hashing algorithm and the shared secret key. If the calculated signature matches the one provided in the request header, the request is considered authentic and can be processed further.
This approach provides a secure and reliable mechanism for verifying the legitimacy of webhook requests, preventing unauthorized access, and ensuring the integrity of the data being transmitted.
Following is an example of how the signature is generated and how to verify it.
const crypto = require('crypto');
const generateSignature = (payload, secret) = {
// Convert payload to string if it's not already
const stringPayload =
typeof payload === 'string' ? payload : JSON.stringify(payload);
// Create HMAC-SHA256 hash using the secret
const hmac = crypto.createHmac('sha256', secret);
hmac.update(stringPayload);
// Return the digest as hex string
return hmac.digest('hex');
};
const payloadExample = {
type: 'userManagement',
data: {
data: [
{
roles: [
{ value: 'admin', label: 'Admin' },
{ value: 'content_creator', label: 'Creator' },
{ value: 'learner', label: 'Learner' },
],
userId: 6505,
fullname: '',
email: 'test@test.com',
status: 'active',
},
],
eventName: 'usersUpdated',
},
timestamp: '2025-03-27T04:25:56.243Z',
};
const secret = '12345fffff222222'
const sign = generateSignature(payloadExample, secret);
const authorizationToken = '2569503a8b0981d3f8186ed7597577d0e720992bceaeb3a110a04f84eb072cae'; // value is retrieved from header Authorization
console.log(
'Is signature valid: ',
sign === authorizationToken
); // should display 'Is signature valid: true'
Events
| Event | Object | Description |
| Learner creation | Learner id, learner email, learner full name, learner account status, timestamp | This event is triggered when a new learner account is added to your HowToo academy. |
| Learner activation | Learner id, learner full name, learner account status, timestamp | This event is triggered when a learner account is activated. |
| Learner deactivation | Learner id, learner full name, learner account status, timestamp | This event is triggered when a learner account is deactivated. |
| Course status update | Course id, course name, course description, course status, score, learner id, learner email, learner full name, timestamp | This event is triggered when a course status is updated (start, complete, etc). |
| Lesson status update | Lesson id, lesson name, lesson description, lesson status, score, learner id, learner email, learner full name, timestamp | This event is triggered when a lesson status is updated (start, complete, etc). |
Embedded Academy course in an iFrame
This feature Enables the embedding of HowToo Academy courses directly into external websites or applications using an iFrame. Learners can then access and complete courses and lessons in the flow of their work activities without leaving the host platform.
Step-by-step guide
- Retrieve the user authentication
tokenandsiteURL from the user launch API (API doc: https://howtoo.stoplight.io/docs/howtoo-api/4qn6jasfu1orw-launch-how-too) - Retrieve the destinated
courseIdfrom search course API (API doc: https://howtoo.stoplight.io/docs/howtoo-api/xmud83if5d0rc-search-courses) or have the course id in place - Launch the course page inside the iframe with the src is
https://<site>/tokenauth.html?token=<token>&redirect=/embeddedCourse/{courseId} - The lesson inside the course will be launched in a new window. It requires the browser to allow it.
Comments
0 comments
Please sign in to leave a comment.