LMS Collaborator knowledge base

Webhooks

Info #

A webhook (also called a web callback or HTTP push API) is a way for an app to provide other applications with real-time information. A webhook delivers data to other applications as it happens, meaning you get data immediately. Unlike typical APIs where you would need to poll for data very frequently in order to get it real-time. This makes webhooks much more efficient for both provider and consumer. The only drawback to webhooks is the difficulty of initially setting them up.
Webhooks are sometimes referred to as “Reverse APIs,” as they give you what amounts to an API spec, and you must design an API for the webhook to use. The webhook will make an HTTP request to your app (typically a POST), and you will then be charged with interpreting it.

General #

Each webhook in LMS Collaborator maks POST request (Content type: application/json) with JSON ecoded body.
Webhook has some default fields in body, this fields will transfer for any webook type. Default fields:

Field Type Description
web_hook_id int unsigned Webhook internal id
web_hook_log_id int unsigned Webhook call id
web_hook_url string Webhook endpount url
web_hook_type string Webhook type
secret string Secret, see Securing section

Securing #

Each webhook has uniquer secret:

This secret will be transfered in body params (parameter secret) and in HTTP header X-Cbr-WebHook-Token. So you can check this secret in you endpoint logic and allow only requests from webhook.

Types #

Currently we support next webhooks:

  • Send notification - will call for any notification to user. It works only for email notifications, so if you turn off email template in notification templates (see System settings) this webhook will not called. Fields:
Column Type Description
user.id int unsigned User internal id
user.uid string User external id
user.email string User internal id
user.fullname string User fullname
user.phone string User phone
event string Internal notification event name
subject string Notification subject
body string Notification body (plain text)
  • Assign task - will call when LMS assign task to user (manually by administrator or automaticaly by rules or trajectories).
    Fields:
Field Type Description
user_id int unsigned User internal id
task_id int unsigned Task id
title string Task title
url string Task url
type string Task type. Possible values: 'test', 'webinar', 'resource', 'separator', 'course', 'polls', 'poll360', 'training-program', 'complex-test', 'workshops', 'meetup', 'check-list'
element_id int unsigned Task element id
tags string Task tags (coma separated)
parent_id int unsigned Task parent id
program_id int unsigned Task program id (If task is part of program)
points int unsigned Task points see Task points
  • Unassign task - will call when administrator unassign task from user.
    Fields:
Field Type Description
user_id int unsigned User internal id
task_id int unsigned Task id
  • Change task status - will call for any users's task status changing.
    Fields:
Field Type Description
user_id int unsigned User internal id
task_id int unsigned Task id
status string Task status. Possible values: 'started', 'inprogress', 'finished', 'verification', 'fail'
  • Change user rating - will call when users's leargnig rating changed see User rating.
    Fields:
Field Type Description
user_id int unsigned User internal id
rating int unsigned Learning rating value

Troubleshooting #

You can find webhook request and responce info in logs.

Currently we store only logs for last 30 days.

Example #

You can find example for handling each webhooks type in
https://github.com/davintoo/webhooks-example-app
This app deployed and runed on Heroku
https://collaborator-web-hooks-example.herokuapp.com/

Still have questions?
Our technical support team is always happy to help!
Write to us at technical support [email protected]. If you are registered on our Helpdesk - send request button below.
Send request