Webhooks allow clients to build or set up integrations that subscribe to activity occurring in the Absorb LMS. When these activities occur, Absorb will send an HTTP request to the Webhook's configured URL listener. For example, a listener can be built to react when a new Learner is created, a Course is completed, or a new Competency is gained.

Absorb offers Webhook Events for both Admin and Learner activities in the LMS. Common uses could be when a Course is completed by a Learner, or when a new Course is created by an Admin.

Webhooks vs. API

There are excellent use cases for both integration methods depending on the individual needs of the client. REST APIs request information from an outside system to the LMS, while Webhooks push information from the LMS to an outside system. Webhooks can be more efficient when an outside system is looking to respond to an activity that occurs in the LMS. To satisfy this using APIs, the outside system would need to poll (or ask the LMS repeatedly) to see if a change has occurred.

APIs are:

• Generally synchronous, where the client sends a request and waits for a response from the server.
• Used to request or send data to a system.

Webhooks are:

• Asynchronous and Event-driven, designed to react to Events rather than requests.
• Efficient. Reduces the need for frequent API polling, decreasing the workload and improving responsiveness.
• Real-time: Enables immediate action based on Event occurrence, which is crucial for time-sensitive operations.

Using Webhooks: What is an Event?

Events represent activity occurring in the LMS about which an outside system can receive notifications. These can be Admin driven activities, like the creation of a new User, or Learner driven activities, like the completion of a Course. The below tables contain all currently available Events:

Administrator Events

• User Created
• Online Course Activated
• Enrollment Completed by Admin
• Department Created
• Department Deleted
• Group Created
• Group Deleted
• Curriculum Activated
• Curriculum Deactivated
• Instructor Led Course Activated
• Instructor Led Course Deactivated
• Online Course Deactivated
• Course Bundle Activated
• Course Bundle Deactivated
• Course Bundle Deleted
• User Enrolled in Course by Admin

Learner Events

• Enrollment Completed by Learner
• Certificate Awarded
• Competency Awarded
• Course Credits Awarded
• Session Enrollment Completed
• Self-Assessment Completed *
• Learning Path Completed *
• User Enrolled in Course by Learner

* Requires Skills subscription

What Does a Standard Payload Look Like?

Webhook notifications from the LMS are intended to be lean. They indicate that a change has occurred, and provide keys to learn more about that change. A typical payload will contain the following data:

• The Event name
• The User ID of the Learner who has taken the action, or for whom the action is on behalf of.
• The ID of the Admin who performed the Event (if this is an Admin Event).
• Information about the transaction - Client ID and Correlation ID.

Webhook Receiver URLs

A Webhook receiver, or listener URL, is a small program intended to receive a standard set of data (the Webhook payload) and then perform an action in response to that notification. Because the Webhook payload is lean, it is typical that a Webhook receiver will also make use of the Absorb Integration API to learn more about the change made to the system which prompted the Event.

Each client Webhook receiver will be unique, as each use case may differ from client to client. You may also require different information from the LMS in order to complete your response to the Event. Using the Integration API to request the information you need will allow you the flexibility necessary to satisfy the response.

As an example, if the Event triggered was a new user creation, then the Webhook receiver may choose to perform a GET call to the API to request all details about that new Learner and then perform an action with the information provided.

Configuring Webhooks

The following section contains the steps necessary to begin set up and begin utilizing Webhooks. Webhook configuration can only be done by a System Administrator.

1. Access the Admin Experience.
2. From the Admin Interface, access the Account menu on the top right of the page.
3. Click Client Settings from the list of available options.
   
    
4. Click the New Webhook button.
   
5. Complete the Webhook configuration form.
   
   • Name: Enter a Name. This Name is internal, for the purposes of recordkeeping.
   • Events: Select from the available Events in the drop-down menu. More than one Event may be selected.
   • URL: Enter a listener URL. This is the location where Event information is sent from the LMS.
   • Secret Key: A value is generated here after the Webhook has been saved. This optionally allows you to include a Signature for verification in your http response.
6. Prior to saving, if the listener being used is ready to accept Webhook Events, an option to test the Webhook listener via the Test Webhook button is available.
   • The interface will show either a success or failure message, along with the response from the listener URL.
   • Example success message:
     
   • Example failure message:
     
7. When all changes are complete, click the Save button at the bottom of the modal window.

Using a Secret Key

A Secret Key allows you to confirm the authenticity of your Webhook by creating, and referencing the absorb-signature header in the HTTP request. This allows you to, optionally, perform a checksum verification for your Webhook. 

Once you have created and saved your Webhook, the Secret Key field will populate with a value.

When you receive a Webhook notification, the generated signature will be included as the absorb-signature header of the HTTP request.

Verifying the absorb-signature Header

To verify that a Webhook request is valid, generate your own HMAC-SHA256 signature locally and compare it to the value provided in the absorb-signature header. Use the displayed Secret Key together with the raw HTTP request body exactly as it is received.

When generating the signature, use only the request body as the input data. Do not add or remove spaces, line breaks, or other formatting, as any change to the request body will produce a different signature value.

1. Copy the Secret Key from the saved Webhook configuration.
2. Capture the raw HTTP request body from the incoming Webhook notification.
3. Generate an HMAC-SHA256 signature using the Secret Key and the raw request body.
4. Compare your generated value to the absorb-signature header included in the request.

If the generated value does not match the absorb-signature header, treat the request as invalid and reject it.

Test Webhook Limitation

The Test Webhook function does not generate the absorb-signature value by using the saved Secret Key. Test requests use a randomly generated signature, so the signature for a test event cannot be validated against the Secret Key.

Verifying the User-Agent Header

Webhook notifications include a User-Agent header in the HTTP request. Clients can use this header to help authenticate, log, or monitor incoming requests as part of their validation and observability workflows.

Best Practices

The following sections contain information pertinent to Webhooks, which may prove valuable. If you have additional questions or concerns related to Webhooks that aren't addressed within the context of this article, please reach out to your Client Success representative.

Test in Sandbox

As with all integrations, testing in production is not advised. Ensure that testing is completed in a sandbox Portal, and only once thoroughly tested, apply the changes to production Portal.

Given that Events are triggered more frequently in production, ensure that the listener URL being utilized is properly configured before moving to a production environment.

Go Live Process

To configure Webhooks in a production Portal, follow the same steps as in a sandbox Portal. Recreate the new Webhook and save this configuration. The receiver URL may be the same as the Sandbox configuration, but this could vary dependent on the use case.