Cal State Training Resources

Webhooks

Updated on

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

  1. Webhooks can only be created in SumTotal by the systemwide LMS team
  2. Campus IT will need to be involved to accept the payload through an API
  3. 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.
  4. Webhooks serve minimum details in the form of skinny payloads. This is done to avoid any performance issues and serve you in real-time.
  5. 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)
  6. Most common event used is the training.attended webhook for tracking attendance on a certain activity by a certain audience

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

  1. Configure a Webhook Endpoint
  2. Test Payload
  3. Add Webhook Filters

Configure a Webhook Endpoint

  1. Endpoints to be set up only using HTTPS endpoints
  2. Select the event to be listed as the endpoint
  3. Copy the Secret Key (key is to make sure you can determine the payload is from SumTotal)

Test Payload

  1. 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.)
  2. 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.

  1. Event
  2. Audience
  3. 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

  1. 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.
  2. 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.
  3. 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:

  1. t = ticks
  2. v1 = signature

Signature will be constructed using 3 different parameters:

  1. Ticks
  2. Event Payload (Request Body)
  3. 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.

https://github.com/sumtotal-services/SumTotal

Previous Article Annual Campus Compliance Steps for Success
Next Article APIs
Still Need Help? Contact Us