Webhooks

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: 123,
        fullname: '',
        email: '[e-mail]',
        status: 'active',
      },
    ],
    eventName: 'usersUpdated',
  },
  timestamp: '2025-03-27T04:25:56.243Z',
};

const secret = 'some_secret'
const sign = generateSignature(payloadExample, secret);

const authorizationToken = 'authorization_token'; // 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).
Course published	Course id, course name, course description, learners enrolled, timestamp	This event is triggered when a new course is published
Course updated	Course id, course name, course description, timestamp	This event is triggered when an existing course is updated and re-published