Overview 

The Litmos Webhooks feature is designed to allow your application to receive notifications when a subscribed event occurs within the LMS.  This guide explains the process for configuring webhooks for your organization. 

Important Note: Please contact your Account manager for this feature to be enabled for your Litmos account 

Configuring Webhooks 

Configuring a webhook endpoint can be completed by logging into your Litmos instance.  Once logged in, follow these simple steps.  

1. From your account profile icon, select Account Settings. From the left-hand menu, click on the Litmos Features menu item.
2. Once you reach the Features screen, click on the Webhooks panel to access the Webhooks configuration screen. (Note: The Litmos Webhooks feature is a premium service. Please contact your Account manager for this feature to be enabled for your Litmos account
3. You have now reached the webhooks configuration screen. This screen will display all webhooks that have been configured including active and inactive.  The first thing you will need to do is enable the feature by clicking the “Enable Webhooks” checkbox and clicking on the Save button.  

Next, click on the Add Webhook button to add your endpoint.  This will route you to the Create Webhook Endpoint screen.

The following steps will need to be completed.

1) Enter your endpoint URL 

Litmos recommends that you have confirmed that your endpoint meets the below criteria: 

• Publicly accessible 
• URL needs to be secure (HTTPS) 
• Endpoint is configured to handle POST requests 
• Endpoint can handle message payloads (JSON)  

2) Choose an Event

Litmos offers 6 hooks for common events:

1. Achievement.Earned (course & learning path)
2. Session.Created (ILT session created)
3. Session.Registration (ILT session user registration)
4. ELearningCourse.Processed (SCORM/TinCan course finished processing)

5. Learner.Overdue (course overdue)

6. Learner.NotCompliant (course compliance expired)

3) Designate the Active Status

When checked, this tells Litmos that to send messages to your configured endpoint. This is similar to subscribing and unsubscribing.

4) Select Authentication Credentials (optional)

A username and password can be used to authorize the webhook event payload at the target endpoint URL. The username and password combo would need to be entered as a "Webhook Credential" in order for the credential to be used with the webhook event.

The username and password must be verified by the domain entered when adding the new credentials. Also, the endpoint URL entered for the specific webhook event must also recognize and authorize that username and password. 

5) Save

Click the "save" button. Once your webhook has been created it will be displayed on the Webhooks screen.

Your created webhook endpoint has also been assigned a signing secret which allows you to verify the authenticity of messages your endpoint receives. To obtain the signing key for your endpoint, click on the Edit link.  This signing key can also be regenerated as needed.

Regenerate Signing Secret 

This is the signing key you will use to verify the signature contained in the request header of messages delivered by the Litmos Webhooks service.  In cases where your signing secret has been compromised, you can assign your endpoint a new signing key by clicking on the Regenerate Secret button.   

Any new messages created by the Litmos webhooks service will use the new signing key to generate the request signature. There may be a period where messages sent by the Litmos Webhook service may be signed using the previous singing secret, therefore we recommend you cater for this scenario when verifying signatures.  

Delete Webhooks Endpoint 

Deleting the webhooks endpoint will permanently remove the endpoint from Litmos and will result is messages no longer being delivered to this endpoint.   

Webhooks Payload 

When the event occurs within the application, the webhooks service will make a POST request to your specified endpoint.  The POST request will be in the UTF-8 charset and will contain a JSON object with details of the event that triggered the webhook.  

• Payload date values are in ISO 8601 format and in UTC  

• The encoded Id values contained in the message body (userId, courseid)  are the same as the id values that are returned from the Litmos API: https://support.litmos.com/hc/en-us/sections/206185047-Developer-API .  
• Example payload for achievement.earned is shown below.

{ 

  "id": 4513, 

  "created": "2019-05-06T01:13:19.533", 

  "type": "achievement.earned", 

  "object": "event", 

  "data": { 

    "userId": "yj-nr8PhW8o1", 

    "userName": "sample", 

    "courseId": "nAcqwEA8jUo1", 

    "title": "Course Demo", 

    "code": "", 

    "achievementDate": "2019-05-06T01:12:35.990", 

    "compliantTilldate": null, 

    "result": "Completed", 

    "type": "Course Completed", 

    "firstName": "Sample", 

    "lastName": "User", 

    "achievementId": 368800, 

    "certificateId": "biZrK8ab0LE1" 

  } 

} 

Request timeout and retry logic 

When the Litmos Webhooks service POSTs the event payload to the webhook endpoint, the service will wait for up to 10 seconds for the client to respond with a valid response code.  Litmos considers the following response codes to represent a successful receipt of the webhook:  

• 200 
• 201 
• 202 

Important Note: Litmos recommends that your endpoint prioritizes sending a valid response before undertaking any processing of the request body to avoid the message delivery being marked as failed and the message delivery re-attempted.

Duplicate messages 

There may be instances where the Litmos Webhooks service may deliver the same webhook multiple times. Litmos recommends that your event processing implements a level of idempotency to cater for these scenarios.  

Retry Logic 

When the Litmos Webhooks service determines that a message delivery failure has occurred, it will re-attempt delivery of that message. The Litmos Webhooks service considers delivery as failed when:  

• An invalid response code is received 
• An endpoint takes longer than 10 seconds to provide a valid response 

We will re-attempt to deliver the message an additional 5 times using an exponential back-off policy.  A message will be considered as permanently failed once all attempts have been exhausted and no further delivery attempts will be made.  

Endpoint Inactivation 

In order to minimize the volume of messages sent to unresponsive endpoints, we will Inactivate your endpoint in the instance where five consecutive permanent failed message deliveries have occurred.   

During this time no further messages will be delivered to your endpoint, and no further events will be created until such time as your endpoint is reactivated.  

An email advising of inactivation will be sent to the user who initially created the endpoint within the Litmos LMS.  

Verification 

For additional security, all messages sent by the Litmos Webhooks service contain some additional request headers.  

• User-Agent: Will contain the value ‘Litmos’ 
• Litmos-Signature:  consists of a timestamp and a signature.  The timestamp is prefixed with t=  and the signature Is prefixed with s= 

Litmos generates this signature using a hash-based code (HMAC) with SHA-256 hashing algorithm.  

To verify the Litmos-Signature:  

1. Take the integer Unix timestamp from the header
2. Append it the body of the payload so the format is: {timestamp}.{MessageBody} 
3. Then using SHA-256 encryption, use the Signing Secret from your webhook endpoint page as the secret and the string above as the text to generate a hash 
4. Compare this Hash with the value of s from the header. If the values do not match, then you should ignore this request to your endpoint.

 The raw content for each of the webhook payloads is shown below in JSON format:

Achievement.Earned (Course)

{
  "id": 7315,
  "created": "2020-10-27T09:15:10.297",
  "type": "achievement.earned",
  "object": "event",
  "data": {
    "userId": "jgEBm_Yoi3s1",
    "userName": "20201019-Learner2",
    "courseId": "g9zUgeZTFR01",
    "title": "Example Course",
    "code": "12345",
    "achievementDate": "2020-11-15T08:36:10.313",
    "compliantTilldate": null,
    "result": "Completed",
    "type": "Course Completed",
    "firstName": "Lenny",
    "lastName": "Litmos",
    "achievementId": 372112,
    "certificateId": null
  }
}

Achievement.Earned (Learning path)

{
  "id": 7315,
  "created": "2020-10-27T09:15:10.859",
  "type": "achievement.earned",
  "object": "event",
  "data": {
    "userId": "jgEBm_Yoi3s1",
    "userName": "LeonardSomtil",
    "learningPathId": "g9zUgeZTFR01",
    "title": "Example Learning Path",
    "code": "12345",
    "achievementDate": "2020-11-15T08:36:10.313",
    "compliantTilldate": null,
    "result": "Completed",
    "type": "Learning Path Completed",
    "firstName": "Leonard",
    "lastName": "Somtil",
    "achievementId": 372113,
    "certificateId": null
  }
}

Session.Created (Instructor led training session)

{
  "id": "BB4slpiG7_81",
  "created": "2020-11-15T20:54:24.64",
  "type": "Session.Created",
  "object": "event",
  "data": {
    "courseId": "4gcvbwSFbGM1",
    "courseName": "Example Course",
    "moduleId": "Qot7aC9eWB81",
    "moduleName": "Example ILT Module Name",
    "sessionId": "BB4slpiG7_81",
    "sessionName": "Example ILT Session Name",
    "sessiondayId": "VBQa1lIxkJQ1",
    "sessionType": "Class Room",
    "sessionUrl": "",
    "sessionNotifications": "Admin1Username,Admin2Username",
    "instructors": "cFjqwRheVgs1",
    "instructorUsernames": "Instructor1Username",
    "startDate": "2020-11-15",
    "endDate": "2020-11-15",
    "startTime": "09:00:00:000",
    "endTime": "11:00:00:000",
    "timeZone": "Pacific Standard Time",
    "location": "c2W2LaORoGE1",
    "locationName": "",
    "resources": "",
    "resourceNames": "",
    "details": "Bring your computer to research sites about Webhooks",
    "seatMinimum": "10",
    "seatMaximum": "20",
    "closeRegistration": "0",
    "closeUnregistration": "0",
    "approvals": "",
    "approvalsUsernames": ""
  }
} 

Session.Registration (Instructor led training session)

{
  "id": "Df_RGP2K2Zk1",
  "created": "2020-11-15T22:29:28.363",
  "type": "Session.Registration",
  "object": "event",
  "data": {
    "courseId": "MEGfeo4cRxc1",
    "courseName": "Example Course",
    "moduleId": "j6HLt844gNM1",
    "moduleName": "Example ILT Module Name",
    "sessionId": "Df_RGP2K2Zk1",
    "sessionName": "Example ILT Session Name",
    "data": {
      "userID": "jgEBm_Yoi3s1",
      "userName": "LeonardSomtil",
      "firstName": "Leonard",
      "lastName": "Somtil",
      "email": "leonard.somtil@sap.com",
      "manager": "j6HLt844gNM1",
      "companyName": "SAPLitmos",
      "workPhone": "9252512220",
      "mobilePhone": "",
      "timeZone": "Pacific Standard Time",
      "language": "English (United States)"
    }
  }
}

eLearningCourse.Processed (AICC, Scorm & xAPI)

{
  "id": "YVLbfqmWZ1c1",
  "created": "2020-11-15T09:14:48.48",
  "type": "ElearningCourse.Processed",
  "object": "event",
  "data": {
    "moduleId": "b892u2iGSV01",
    "originalId": "1169793",
    "moduleName": "Example Tin Can Course File",
    "moduleDescription": "Example Module Description Text",
    "code": "TC123",
    "createdBy": "68779",
    "createdByUsername": "Leonard.Somtil@sap.com",
    "createdDate": "2020-11-15T09:12:46.337",
    "status": "Success",
    "active": "1"
  }
}

Learner.Overdue (Course)

{
  "id": 4513,
  "created": "2020-02-19T17:34:46.12",
  "type": "Learner.overdue",
  "object": "event",
  "data": {
    "userId": "jgEBm_Yoi3s1",
    "userName": "LeonardSomtil",
    "firstName": "Leonard",
    "lastName": "Somtil",
    "courseId": "eo4cREA8jUo1",
    "courseName": "Course Demo 2",
    "code": "CourseRefCode",
    "overdueType": “Specific Date”,
    "overdueDate”: "2020-02-19T17:20:11.00",
    “automaticRetake”: “180”,
  }
}

Learner.NotCompliant (Course)

{
  "id": KSJdxoqPA9y7,
  "created": "2020-02-19T17:34:46.12",
  "type": "Learner.notcompliant",
  "object": "event",
  "data": {
    "userId": "jgEBm_Yoi3s1",
    "userName": "LeonardSomtil",
    "firstName": "Somtil",
    "lastName": "User",
    "courseId": "nAcqwEA8jUo1",
    "courseName": "Course Demo",
    "code": "CourseRefCode",
    "compliantTilldate": "2020-02-19T17:00:00.00",
    "complianceType": “Time Span”,
    "complianceBasedOn": "Completion Date"
    “compliantFor”: “365”,
    "automaticEmailreminder": "7",
    “automaticRetake”: “180”,
  }
}