SumTotal-created webhooks are web applications that allow custom callbacks for customers. These webhooks are set up and managed by customers using webhooks SumTotal provides.
Webhooks are like APIs —but more straightforward. An API is a complete language for an app with functions or calls to add, edit, and retrieve data. On the other hand, Webhooks are for one specific part of an app, and they are automated. You might have a webhook just for new activities—and whenever a new activity is created, the application will automatically push the data to the other application's Webhook URL. The data is a JSON message and sent as an HTTP POST. It is a simple, one-to-one connection that runs automatically.
Need to know
- Webhooks can only be created in SumTotal by the systemwide LMS team
- Campus IT will need to be involved to accept the payload through an API
- Configure your Webhooks to only receive the relevant event Listening to extra events (or all events) may put undue strain on your system and is not recommended.
- Webhooks serve minimum details in the form of skinny payloads. This is done to avoid any performance issues and serve you in real-time.
- New webhooks are added frequently every release, please feel free to review the latest documentation on the LMS SharePoint site. (search “webhooks” in the Core Platform guide)
- Most common event used is the training.attended webhook for tracking attendance on a certain activity by a certain audience
Table of Contents
Setting Up Webhooks
Setting up webhooks in CSU Learn can only be done by a system administrator at the Chancellor’s Office. To initiate this process, please open a ticket to start discussion of the webhook need and process.
The process is outlined as follows
- Configure a Webhook Endpoint
- Test Payload
- Add Webhook Filters
Configure a Webhook Endpoint
- Endpoints to be set up only using HTTPS endpoints
- Select the event to be listed as the endpoint
- Copy the Secret Key (key is to make sure you can determine the payload is from SumTotal)
Test Payload
- Selecting a save webhook event and clicking SEND (This is a sample request to determine if your destination endpoint is accessible from the SumTotal platform.)
- Success or Error will be sent via HTTP status (See Appendix C for sample)
Webhooks--Caching
| Configuration Item | Cache Time | Notes |
| Webhook Filters | 15 minutes | If you use Audience or Activity filters at webhook endpoints, there is a 15 minutes cache refresh interval. For example, any data updates to audience or activity filters are cached for 15 mins and refreshed again. |
Webhook Filters
Once successful completion of payload testing, audience and activity filters can be added to the webhook for accurate reporting on the event to be captured / monitored. There are three main filters in which allows the webhook to run efficiently.
- Event
- Audience
- Activity
Event
The event is the webhook to be used to capture information. The most commonly used event is training.attended which will send a payload any time a user (within the audience) completes the (specified) activity.
Audience
The audience is defined by a set of rules to capture a specific audience. The rules should be simple and configured prior to setting up a webhook. The audiences are built in the same way (and in the same area, Administration > Quick Links > Audiences) as audiences for assignment, reporting or any other needs. Best practice is to set up the audiences with webhook in the name, ID and description so it doesn’t get inadvertently deleted. Only one audience can be attached to a webhook.
Note: Audience Refresh or frequent changes to the Audiences can impact the evaluation of the Audience filter before the webhook payload is sent.
Activity
The activity in most events will define which activity you are looking for the payload to trigger from. A webhook can only have one activity filter per event.
Webhook Filtering Best Practices
- If you are planning to use audiences for webhook filters, prefix your audience name to have “webhook-“ and add some description to say who is the owner of the audience and its purpose. This helps prevent other administrators changing the audience configuration or deleting them without contacting the owner of the audience.
- Though audiences support many rules, when using it for webhooks, keep the audience rules simple by not adding too many rulesets or rules. For example, your rule could be users from a domain or a particular organization.
- The Activity Filter supports three rules as of this release; however, keep the filter simple by not adding too many rulesets or rules. E.g., 1: activities from a domain. E.g., 2: selective activities E.g., 3 particular Activity Types.
Appendix A: Supported Webhook Events
The following are the webhook events available and what filters are available for each event.
| Webhook | Audience Filter Supported | Activity Filter Supported |
| activity.created | Yes | |
| activity.deleted | Yes | |
| activity.expressinterest | Yes | Yes |
| activity.favorite | Yes | Yes |
| assignment.created | Yes | |
| assignment.deleted | Yes | Yes |
| assignment.updated | Yes | Yes |
| gamification.badge_assigned | Yes | |
| gamification.points_accrued | Yes | |
| recruiting.phase_changed | Yes | |
| training.attended | Yes | Yes |
| training.attendedbutpendingsignature | Yes | Yes |
| training.cancelled | Yes | Yes |
| training.decertified | Yes | Yes |
| training.inprogress | Yes | Yes |
| training.launched | Yes | Yes |
| training.noshow | Yes | Yes |
| training.recertified | Yes | Yes |
| training.registered* | Yes | Yes |
| training.removed | Yes | |
| training.replaced | Yes | Yes |
| training.updated | Yes | |
| training.waived | Yes | Yes |
| training.waivedbutpendingsignature | Yes | Yes |
| user.accountlocked | Yes | |
| user.skillacquired | Yes |
*training.registered event in an Activity filter works based on the root activityId. That is, if a user is registering for a curriculum structure, the curriculum filters by the root activityId, irrespective of participating activities in that curriculum.
Appendix B: Webhook Definitions
Below is a list of SOAP or REST API business events published as Webhooks
gamification.points_accrued
When does this event occur?
- Whenever a user either completes a Learning activity (also via TMU/Admin roster updates) or any Social task which is set to provide points to the user as per gamification rulesets
Integration Examples
- You may have an Analytics tool where you create reports/dashboards on gamification events. Rather than depending on API/AR reports, you can just configure a webhook URL to listen to the events.
- You may have an in-house or 3rd party application where you fetch points from SumTotal and other sources to let users consume those points as rewards elsewhere. Rather than pulling the point transactions via APIs, customers can now configure a webhook URL to listen to the events.
training.attended
When does this event occur?
- This Event is generated whenever a user is marked as attended on the roster, irrespective of completion and pass status.
Integration examples
- Activity or Training attendance is one of the most sought-after events which customers currently pull via AR reports or APIs or SOAP methods for transcripts and user progress. With a Push mechanism now in place, you can try testing fetching attendance via this event and push it to your downstream integrations.
training.updated
When does this event occur?
- This event is generated whenever the attempt is updated. The event will be triggered when at least one of the fields in the payload below is modified.
- This event might be trigged along with the other training status change events when there is a change in status.
- This event will be triggered for activity structures and single node activities.
- This event can be occurred through any means i.e., Learner completion, Roster Updates, TMU, Web Services, Rest API
- It is recommended to avoid using this event unless absolutely necessary, as you might see too many events triggered whenever something gets updated on the roster, this is performance intensive event. If you are looking for a particular status, please use one of those specific business events than this event.
training.removed
When does this event occur?
- This event is generated whenever admin removes an attempt from the roster or triggered when an activity is deleted.
- This event will be triggered for activity structures and single node activities.
training.launched
When does this event occur?
- This Event is generated whenever a user launches an activity from any of the following:
- Learner view.
- Mobile.
- This is applicable for all launchable types except "Knowledge Document."
- For Knowledge documents, training.attended event gets triggered as there is always going to just mark it as attended on roster by default.
- If the launchCount=1, it can be considered as in progress for the first time launch, and if the launchcount is greater than 1, it means user has launched the course again.
training.inprogress
When does this event occur?
- This Event is generated whenever training status is changed as In Progress actions from :.
- Roster update
- Training Migration Utility
- SOAP or Rest API
- Instructor Schedule
- This event will NOT be generated when user launches a launchable activity where training.launched event is generated instead.
- This event will be triggered for standalone & child activities.
training. waivedbutpendingsignature
When does this event occur?
- This event is generated whenever the activity configured with electronic signature and admin marks an attempt as waived from roster, TMU, API and SOAP API.
- This event will be triggered for activity structures and single node activities.
- Additionally, The Waived event will be triggered when the signature is provided and the status changes from Pending Signature to Waived.
training. attendedbutpendingsignature
When does this event occur?
- This event is generated whenever the activity configured with electronic signature and learner completes the activity or user marks an attempt as completed from roster, TMU, REST API and SOAP API.
- This event will be triggered for activity structures and single node activities.
- Additionally, The Attended event will be triggered when the signature is provided and the status changes from Pending Signature to Attended.
training.cancelled
When does this event occur?
- This Event is generated whenever user training is cancelled (Not the learning activity itself) through any of the following,
- Learner workflow
- Roster update
- TMU
- Rest API
- SOAP API
- Mobile
- This event will be triggered for standalone and child activities.
training.replaced
When does this event occur?
- This Event is generated whenever a user registration is transferred to another user for an activity by admin, instructor or manager.
- This event will be triggered for Standalone and Child activities.
training.noshow
When does this event occur?
- This Event is generated whenever a user registration status is changed to No Showthrough any of the following,
- Roster update for an activity by admin, instructor or manager.
- TMU
- SOAP API
- Rest API.
- This event will be triggered for Standalone and child activities (leaf node)
training.waived
When does this event occur?
- This Event is generated whenever a user registration status is changed to waived through any of the following,
- Roster update for an activity by admin, instructor or manager.
- TMU
- SOAP API
- Rest API.
- In parent-child activity structures this event is generated at both the root and child level
- For events which are triggered from API and SOAP API , ' WaivedNotes ' field in " tbl_tmx_attempt " table will not be updated with waived reason. Another field ' Note ' field will be updated. So for payloads triggered using API and SOAP API , ' WaivedNotes ' value will be null.
- For waived events triggered from TMU , payload value in ' WaivedNotes ' will be "Waived marked by DATAMIG".f
training.recertified
When does this event occur?
- This Event is generated whenever decertification status is removed from attempt.
- This will be applicable from Certification view in Roster to change for a Decertified training record (to Acquired).
training.decertified
When does this event occur?
- This Event is generated when a certification expired/acquired activity is decertified through
- Activity Roster
- Training Analysis view emulated by Manager from Manager Dashboard
- Training Analysis view emulated by user who have emulation and Decertify acquired certification Learning Management role permissions.
- Training Analysis view of user details page.
user.skillacquired
When does this event occur?
Whenever user acquires Skill through any of the following ways:
- Admin adds skill through UI on user profile.
- Acquired skills imported via Data Import
- Training (has skills linked) is marked as completed through REST API or SOAP API
- Completing training (skills linked) through web or mobile app or even when admin adds user to roster
- It will take up to 5 mins. to trigger this event.
Integration examples
- When user acquires a skill, enable access to other applications which needs that particular skill
- Alert other communities or add users to other skill groups
user.accountlocked
When does this event occur?
Whenever user account gets locked due based on password policy rules either from Web or mobile app, this event gets triggered instantly
Integration examples
- When user account gets locked, listen to this business event and generate a support ticket in another system or monitor account locks in another central access locations.
activity.created
When does this event occur?
Whenever a learning activity is created through the following paths, this event gets triggered for root nodes when activities are moved to production.
- Activities imported through Edx & Kpoint
- Activities are imported through Skillsoft Percipio content
- Activities are imported through LinkedIn
- Activities are imported through Coursera
- Through TMU
- New Activity Builder UI (AMS)
- Content Integrations (AMS) – Udemy
- Staging editor, Activity Wizard, FileUpload, Mobile App(Crowdsourcing)
This event gets triggered in near realtime depending on the system load at that point of time.
Activities which are only in staging mode will not trigger this event.
- Whenever a Skillsoft micro-learning video is converted into a learning activity in SumTotal, the activity.created event is pushed to any subscribing downstream applications.
- Default payload contains just activityId and dateCreated. Additional details can be added to payload by configuring AdditionalPayload.
activity.deleted
When does this event occur?
- Whenever a learning activity is deleted, this event gets triggered.
- Deletion could be from either of the following routes:
- Learning activity listing page
- Any child or subscribed activity deletion via Staging editor
- This event gets triggered in near realtime depending on the system load at that point of time.
activity.expressInterest
When does this event occur?
This event gets triggered instantly whenever user expresses interest on an activity.
Whenever learner expresses their interest on a given activity, usually this happens on schedule activities when there is no capacity or dates not available as per the user choice, then users express their interest, then this event gets triggered.
Integration examples
- Show related topics or other materials on external LXP type applications
activity.favorite
When does this event occur?
This event gets triggered instantly whenever user marks an activity as favorite or removes it from favorites from UI or Mobile App from any path possible ( including widgets)
Integration examples
- Show related topics or other materials on external LXP type applications
recruiting.phase_changed
When does this event occur?
- When a candidate is moved to a phase for the first time, and the 'Phase Set Date' is set for the first time, the event is triggered.
- If the phase is skipped, the webhook will not be triggered.
assignment.created
When does this event occur?
Whenever a learning activity is assigned to a user this event gets triggered.
- The assignment can be direct, Job, Org, or through the audience. Payload gets generated with summarized information about the assignment
e.g. If an activity is assigned through job and orgniazation as well, it will trigger summarized assignment information with objectType denoting how the assignment has happened. - Payload is generated on default schedule. (every 1hr)
assignment.removed
When does this event occur?
Whenever a learning activity assignment is completely removed from a user this event gets triggered.
- Payload is generated on default schedule (every 1hr)
assignment.updated
When does this event occur?
Whenever a learning activity assignment is modified this event gets triggered.
- Assignment can be directly, Job, Org through audience, it will give summarized information of the assignment to the user.
- If assignment is added initially to user, but later through job or via any other objects, only updated event gets triggered because an assignment is already present but only details get changed.
- Payload is generated on default schedule. (every 1hr)
training.registered
When does this event occur?
Registration event gets triggered for both single node as well as structures. If registration is for a structure, actual registration happens at leaf nodes and leaf node activity details will be sent.
E.g. When enrolling on a curriculum, curriculum will be considered as root activity and leaf node where actual registration happens will be sent in registrationDetails node
This event gets triggered in the following scenarios,
- API or SOAP API is called to set status as registered.
- Enrolling from instructor roster or activity roster.
- Users enrol themselves through UI or mobile app
- User is registered through TMU
- When roster status is set to “registered” from other eligible statuses
user.accountcreated
When does this event occur?
Whenever a new user is created in SumTotal, the User Account Created (UserAccountCreatedEvent) webhook is triggered to notify any subscribing applications. The following scenarios would trigger this notification:
- User created through admin user interface
- User created through REST/SOAP APIs
- User created through Data Import
- User created through Self-Account creation
- Recruiting
- No filters are available for this event
- “DetailedPayload” configuration is supported.
user.accountupdated
When does this event occur?
Whenever an existing user’s record is updated in SumTotal, User Account Updated (UserAccountUpdatedEvent) webhook is triggered to subscribed applications (end points configured). The following scenarios would trigger this notification:
- User created through admin user interface
- User created through REST/SOAP APIs
- User created through Data Import
- User created through Self-Account creation
- Recruiting
- No filters are available for this event
- “DetailedPayload” configuration is supported.
user.delete
When does this event occur?
User account delete event in SumTotal is now pushed in a webhook, user.delete, so interested systems can get this information. For example, if user is deleted, other systems will need to know to delete all personally identifiable information for this user. This webhook will trigger when the following scenarios occur:
- User is deleted through UI (Remove & GDPR deletion)
- User is marked for deletion through DataImport
- User is deleted through REST API or SOAP.
- From Data import and Remove account workflow, first soft deletion happens and the payload will be generated with hardDelete as 0. Once the GDPR is also processed, then hard deletion happens and the payload will be generated with hardDelete as 1.
- If the user is deleted directly from GDPR, then only hard deletion payload will be generated with the flag hardDelete as 1.
- No filters are available for this event as when the user is deleted user is no longer part of any audiences.
- “DetailedPayload” configuration is not supported.
activity.expired
When does this event occur?
Whenever Learning Activity has reached its expiry date (Not user certification expiry date) SumTotal, the activity.expired webhook pushes information to any applications listening to the webhook. Activity filter is supported with this webhook.
- If expiry date is set to future date on already expired activity, it generates event when it expires next time.
- Supports “AdditionalPayload” configuration
- Activity Filter is supported.Any expiry events get generated on scheduled basis based on “Activity Expiration Processor” service, which is scheduled to run 2 am every day.
activity.updated – Beta
When does this event occur?
When a learning activity is modified from the staging editor, the activity.updated(Beta) webhook event gets triggered. This webhook is in Beta, so it is subject to change in future releases without notice. We would like to hear your feedback.
- Event gets triggered in realtime (instant).
- Activity Filter is supported
- “DetailedPayload” configuration is not supported.
- Activity updated event gets triggered only when values are changed in any of the following sections of activity staging editor
| General Propertied->General |
| General Propertied->Status |
| General Propertied->Notes |
| General Propertied->Certification |
| General Propertied->Grading and Completion |
| General Propertied->Translated Properties |
| Metadata->System Defined |
| Metadata->Optional information |
| Metadata->User Defined |
| Metadata->Activity Filters |
| Costs->General |
| Related Activities->Fulfillment Links |
| Related Activities->Continuing Education |
| Schedule->General |
| Web Based Training->General |
| Web Based Training->Quick Assessments |
| Web Based Training->Redirect Settings |
| Registration->Availability |
| Registration->Audiences |
| Registration->Allocations |
| Registration->Pre-requisites |
| Registration->Evaluations |
| Registration->Rating |
| Registration->Auto-Registration |
| Registration->Auto-Cancellation |
| Registration->Jobs |
| Registration->Organizations |
| Resources->Instructors |
| Resources->Locations |
| Resources->Vendors |
| Resources->Equipment |
| Resources->Attachments |
| Skill and Competencies->Skills |
| Skill and Competencies->Competencies |
| Notifications->System |
| Notifications->Mobile Push Alerts |
| Management->Users |
| Management->Domains |
| Management->Organizations |
| Management->Jobs |
| Management->Topics |
| Social Collaboration->Social |
| Extended Enterprise->Properties |
| Extended Enterprise->Pricing |
| Gamification->General |
activity.rated
When does this event occur?
This new webhook informs registered endpoints when user rates training they completed. This rating can be face-to-face training the user attended, an online course, or Instructor-Led Training (ILT). This payload supports Activity and Audience filters, and this event supports ”DetailedPayload” configuration.
Example
- A dashboard on external portals to show list of most rated courses in real time and refresh whenever someone rates an activity.
- Integrate with reward schemes in real time to encourage users for rating a training that they have completed
Appendix C: Payload Delivery Headers (Example)
The following is an example of payload and delivery headers for reference. Additional testing with the events used, will be best practice to see test payload information and headers to be received.
| x-tenantkey | AU09_SALES_TEST | |
| x-sumt-eventid | 1ff406cb-3c49-11ea-ac62-6287af928f5b | Unique Identifier for each event |
| x-sumtdeliveryid | ee187908-3c4a-11ea-8f61-ff0ae07ef578 | Unique Identifier for a Webhook delivery |
| x-sumt-event | gamification.points_accrued | Event key |
| x-sumtsignature | t=637152071108049194, v1=903159b5d08b0cb5038fb4d7af50d493f2f26059 |
t = ticks v1 =signature |
In the Add/Edit Webhook slide-out screen, you will find a secret key that is auto-generated. Use this secret key to build trust to ensure that the delivery to your endpoint is coming from SumTotal.
Below are the details on how you can code this piece:
The x-sumt-signature header has 2 parts:
- t = ticks
- v1 = signature
Signature will be constructed using 3 different parameters:
- Ticks
- Event Payload (Request Body)
- Secret Key
v1 is the signatureVal which you will have to check against and is computed using the below algorithm:
payloadToSign = timestamp+”.”+payload
i.e. string payloadToSign = string.Join(".", timestamp, payLoad); // timestamp is nothing but ticks (t)
A sample C Sharp code project for consuming SumTotal Webhooks, includes sample to validate signature.