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/