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. 

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

Configuring Webhooks 

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

From your account profile icon, select Account Settings 

From the left-hand menu, click on the Litmos Features menu item 

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 

 

You have now reached the webhooks configuration screen. This screen will display any previously configured webhook endpoints and whether they are currently Active or not.  The first thing you will need to do is enable the feature by placing a tick in the “Enable Webhooks” checkbox and clicking on the Save button.  

 

 

 

Click on the Add Webhook button to add your endpoint 

You’ve now reached the Create Webhook Endpoint screen, here you will need to: 

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)  

Event 

This is the event that your endpoint subscribed to. Currently Litmos only supports one event (achievement.earned), however more events will be added at a later point.   

Active 

When checked, this tells Litmos that to send messages to your configured endpoint. 

 

Click on 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 singing key for your endpoint, click on the Edit link.  

From the Edit webhooks screen you’re able to  

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 

Whan an event occurs within the LMS (currently only one event is available to be subscribed to), the Litmos 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.  

Currently the Litmos webhooks feature has one event available for subscription: achivement.earned,  additional events will be added at a future point in time.  

• 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 .  

achievement.earned payload

{    "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 webhook to your endpoint, it will wait up to 10 seconds for your endpoint to respond with a valid response code.  Litmos considers the following response codes to represent a successful receipt of the webhook:  

• 200 
• 201 

• 202 

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.  

Retry Logic

1 min (60s) after most recent failure

5 min (300s) after most recent failure

30 min (1800s) after most recent failure

60 min (3600s) after most recent failure

360 min (21600s) after most recent failure

 

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.  

To verify the Litmos-Signature:  

1. Take the timestamp from the header (as a string) 
2. Append . 
3. Append the body of the payload so the format is: {timestamp}.{MessageBody} 
4. Then using HMAC 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 
5. 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.