Creating and Managing Webhooks

Discover how to create, manage and send webhooks in your platform

Last Updated

January 29th, 2019

Reading Time

12 min

Version

User Level

Introduction

In Docebo, you can create webhooks to trigger once an event occurs in your platform, sending you information about that event to a specific Payload URL. This allows you to collect data from your learning platform to build reports, integrations, dashboards and more. You can also connect to your HCM, email non-LMS users about actions that occur in the platform, or update your CSM.

Once you’ve activated the Webhooks app in your platform, you can create an input of an initial event, then Docebo sends you a post to a given URL that you set for the webhook paired with that event. Docebo puts the data related to that event into a JSON message and send it to you via an HTTP POST call (not via email or notifications).

You can also create webhooks via the full set of webhook APIs provided by Docebo. Refer to the official API documentation for more information. Note that more webhook functionality will be built over time to include various integrations and more events, so stay tuned the the Product Updates page in the future.

Please note: For performance reasons, you can have only five webhooks enabled in your platform at one time. Each webhook can have only eight events per webhook. Keep this in mind when creating and enabling your webhooks.

This article outlines how to activate the Webhooks app, how to create and manage webhooks, events to include in your webhooks, JSON descriptions for each event, information for payloads and throttles, and other important notes that you need to know to use webhooks in your platform.

Please note that the Webhooks app is available for Enterprise customers only, and this app can only be managed by Superadmins. Power Users have no permissions to view or manage webhooks.

Activating the App

Login to your Docebo platform as the Superadmin. Access the Admin Menu from the gear icon in the header of your platform, then select the Add New Apps item in the menu. Once you’re in this area, select the Additional Features tab in the tab menu on the left side. Then, find the app in the list and press the Activate App button. Read the description in the pop up box, then press Activate Now. The app is now active in your LMS.

Creating Webhooks

Once the app is activated, you can manage it by accessing the Admin Menu, then pressing the Manage item in the Webhooks section. On the main Webhooks page, you can add and manage all of your webhooks, enable or disable them, edit or delete them, and check the last external system error from a webhook (if any).

To add a webhook, press the plus button in the top right corner of the page. On the configuration page, begin in the General section. Add a Name for your webhook. This is the name used internally inside of your platform, so you can give it any identifiable name that you choose. Then, add the Payload URL to where the information from the webhook will be sent.

webhooks create

Please note: The Payload URL must be a properly formatted HTTP/S URL. You can insert one Payload URL per webhook, and you can add up to eight events per webhook, so you can send information for more than one event to this receiving single Payload URL.

In the Events section, press the Select Events button to add events to the webhook. In the slideout panel, flag up to eight events to include in the webhook, then press Confirm. For more information on each webhook and the corresponding JSON codes for them, refer to the corresponding section in this article. You will then see the Events field populate with your selected events, and you can remove them at any time using the X icon next to each event.

Then, move to the Authentication section, where you can switch the toggle to Enable Basic Auth for your receiving endpoint. If enabled, you then need to insert your basic auth username and password in the corresponding fields in the Protocol Info section.

Please Note: Docebo highly recommends using HTTPS and enabling basic auth when using webhooks, as it adds security to the information that the platform sends to your endpoint.

Once you’ve finished configuring your new webhook, press the Save Changes button to create your webhook. The new webhook will appear in the list on the main Webhooks page and will be disabled by default. Refer to the corresponding sections below for how to disable, re-enable, edit or delete your webhooks.

Responding to Webhooks

To acknowledge the receipt of a webhook, Docebo expects a 2xx HTTP status code in response or a 3xx HTTP status. In any other case, Docebo will mark the sending as a failure. Please refer to Error Management section of this article for more details.

Events

course.deleted

  • course_id –  ID of the course
  • course_name – name of the course
  • course_code – code of the course
  • deletion_date – date of the deletion (in YYYY-MM-DD hh:mm:ss UTC)
  • fired_at – date and time of the moment the event has been fired in UTC in YYYY-MM-DD HH:mm:ss

Example:

{
 "message_id": "wh-638ce960-1363-11e9-a15d-d1c47c8f7593",
 "event": "course.deleted",
 "payload": {
   "course_id": 15533,
   "course_name": "A Course",
   "course_code": "common-course-1",
   "deletion_date": "2019-01-08 16:35:05",
   "fired_at": "2019-01-08 16:35:05"
 }
}

course.enrollment.created

  • user_id – ID of the user
  • course_id – ID of the course
  • level – the enrollment level of the user (learner, tutor, instructor, coach)
  • enrollment_date – date of the enrollment
  • enrollment_date_begin_validity – start of the validity period for the enrollment
  • enrollment_date_end_validity – end of the validity period
  • fired_at – date and time of the moment the event has been fired in UTC in YYYY-MM-DD HH:mm:ss

Example:

{
 "message_id": "wh-638ce960-1363-11e9-a15d-d1c47c8f7593",
 "event": "course.enrollment.created",
 "payload": {
   "user_id": 12301,
   "course_id": 15533,
   "level": "learner",
   "enrollment_date": "2019-01-08 16:35:05",
   "enrollment_date_begin_validity": "2019-01-09 16:35:05",
   "enrollment_date_end_validity": "2019-01-10 16:35:05",
   "fired_at": "2019-01-08 16:35:05"
 }
}

course.enrollment.completed

  • user_id – ID of the user
  • course_id – ID of the course
  • completion_date – date of the completion
  • fired_at – date and time of the moment the event has been fired in UTC in YYYY-MM-DD HH:mm:ss

Example:

{
 "message_id": "wh-638ce960-1363-11e9-a15d-d1c47c8f7593",
 "event": "course.enrollment.completed",
 "payload": {
   "user_id": 12301,
   "course_id": 15533,
   "completion_date": "2019-01-08 16:35:05",
   "fired_at": "2019-01-08 16:35:05"
 }
}

course.enrollment.deleted

  • user_id – ID of the user enrolled
  • course_id – ID of the course to which the user is enrolled
  • fired_at – date and time of the moment the event has been fired in UTC in YYYY-MM-DD HH:mm:ss

Example:

{
 "message_id": "wh-638ce960-1363-11e9-a15d-d1c47c8f7593",
 "event": "course.enrollment.deleted",
 "payload": {
   "user_id": 12301,
   "course_id": 15533,
   "fired_at": "2019-01-08 16:35:05"
 }
}

branch.deleted

  • branch_id – ID of the deleted branch
  • fired_at – date and time of the moment the event has been fired in UTC in YYYY-MM-DD HH:mm:ss

Example:

{
 "message_id": "wh-638ce960-1363-11e9-a15d-d1c47c8f7593",
 "event": "branch.deleted",
 "payload": {
   "branch_id": 66301,
   "fired_at": "2019-01-08 16:35:05"
 }
}

branch.user.added

  • user_id – ID of the user added to the branch
  • branch_id – ID of the branch to which the user has been added
  • fired_at – date and time of the moment the event has been fired in UTC in YYYY-MM-DD HH:mm:ss

Example:

{
 "message_id": "wh-638ce960-1363-11e9-a15d-d1c47c8f7593",
 "event": "branch.user.added",
 "payload": {
   "user_id": 12301,
   "branch_id": 66301,
   "fired_at": "2019-01-08 16:35:05"
 }
}

branch.user.removed

  • user_id – ID of the user removed from the branch
  • branch_id – ID of the branch from which the user has been removed
  • fired_at – date and time of the moment the event has been fired in UTC in YYYY-MM-DD HH:mm:ss

Example:

{
 "message_id": "wh-638ce960-1363-11e9-a15d-d1c47c8f7593",
 "event": "branch.user.removed",
 "payload": {
   "user_id": 12301,
   "branch_id": 66301,
   "fired_at": "2019-01-08 16:35:05"
 }
}

user.created

  • user_id – the newly created ID for the new user
  • username – the username of the new user
  • email – the email for the newly created user
  • creation_date – the date of creation for the user, in format YYYY-MM-DD HH:mm:ss UTC
  • level – the level of the user created
  • firstname – the first name of the user (it can be null)
  • lastname – the last name of the user (it can be null)
  • fired_at – date and time of the moment the event has been fired in UTC in YYYY-MM-DD HH:mm:ss

Example:

{
 "message_id": "wh-638ce960-1363-11e9-a15d-d1c47c8f7593",
 "event": "user.created",
 "payload": {
   "user_id": 12301,
   "username": "anna.smith",
   "email": "anna.smith@provider.com",
   "creation_date": "2019-01-08 16:35:05",
   "level": "", 
   "firstname": "Anna",
   "lastname": "Smith",
   "fired_at": "2019-01-08 16:35:05"
 }
}

user.selfregistered

  • user_id – the newly created ID for the new user
  • username – the username of the new user
  • password – the base 64 encoded password
  • email – the email for the newly created user
  • creation_date – the date of creation for the user, in format YYYY-MM-DD HH:mm:ss UTC
  • level – the level of the user created
  • firstname – the first name of the user (it can be null)
  • lastname . the last name of the user (it can be null)
  • fired_at – date and time of the moment the event has been fired in UTC in YYYY-MM-DD HH:mm:ss

Example:

{
 "message_id": "wh-638ce960-1363-11e9-a15d-d1c47c8f7593",
 "event": "user.created",
 "payload": {
   "user_id": 12301,
   "username": "anna.smith",
   "email": "anna.smith@provider.com",
   "creation_date": "2019-01-08 16:35:05",
   "level": "",
   "firstname": "Anna",
   "lastname": "Smith",
   "fired_at": "2019-01-08 16:35:05"
 }
}

user.deleted

  • user_id – the ID of the deleted user
  • deletion_date – the date of deletion of the user, in format YYYY-MM-DD HH:mm:ss UTC
  • fired_at – date and time of the moment the event has been fired in UTC in YYYY-MM-DD HH:mm:ss

Example:

{
 "message_id": "wh-638ce960-1363-11e9-a15d-d1c47c8f7593",
 "event": "user.deleted",
 "payload": {
   "user_id": 12301,
   "deletion_date": "2019-01-08 16:35:05",
   "fired_at": "2019-01-08 16:35:05"
 }
}

user.updated

  • user_id – the newly created id for the new user
  • username – the username of the new user
  • email – the email for the newly created user
  • update_date – the date of update for the user, in format YYYY-MM-DD HH:mm:ss UTC
  • level – the level of the user created
  • firstname – the first name of the user (it can be null)
  • lastname – the last name of the user (it can be null)
  • fired_at – date and time of the moment the event has been fired in UTC in YYYY-MM-DD HH:mm:ss

Example:

{
 "message_id": "wh-638ce960-1363-11e9-a15d-d1c47c8f7593",
 "event": "user.updated",
 "payload": {
   "user_id": 12301,
   "username": "anna.smith",
   "email": "anna.smith@provider.com",
   "update_date": "2019-01-08 16:35:05",
   "level": "",
   "firstname": "Anna",
   "lastname": "Smith",
   "fired_at": "2019-01-08 16:35:05"
 }
}

Editing or Deleting Webhooks

All of your webhooks will appear in the list on the main Webhooks page. Once created, you can edit any of the information that you configured at any time. Scroll your mouse over the webhook in the list, then press the ellipsis icon in the webhook’s row. In the dropdown menu, select the Edit item.

You’ll be redirected to the configuration page of the webhook, where you can edit any of the fields that you previously configured, including the name, Payload URL, events in the webhook, and the basic auth information. When finished with your edits, press Save Changes.

To delete a webhook, scroll your mouse over the webhook in the list, then press the ellipsis icon in the webhook’s row. In the drop-down menu, select the Delete item. Confirm your choice in the pop-up message by flagging that you want to proceed and pressing Confirm.

webhooks edit

Keep in mind that deleting a webhook will completely eliminate the option to use it again in the future. If you are simply not wanting to run the webhook for a temporary period of time, use the disable functionality instead. Before deleting a webhook, be sure that you’ve received all of the information that you’re needing to receive prior to confirming the deletion. Note also that deleting the webhook will not delete any data that you previously sent.

Important Note about Editing or Deleting Webhooks: When you edit or delete a webhook, keep in mind that the change may not take place immediately. Webhooks form a work queue for Docebo, so any work that is still running or in the work queue before the changes took place will still be sent to the configured endpoint for the webhook at the time that the webhook triggered.

Enabling or Disabling Webhooks

The check mark in a webhook’s Status column on the main Webhooks page allows you to quickly view and change which webhooks are currently enabled or disabled. A green check mark means that the webhook is enabled to run, while the grey check mark means that the webhook is disabled and will therefore not trigger.

webhooks enable

Simply press the check mark in the webhook’s row to enable or disable it. Remember that you can only have five webhooks enabled at a time.

Important Notes about Disabling Webhooks: When you disable a webhook, keep in mind that the change may not take place immediately. Webhooks form a work queue for Docebo, so any work that is still running or in the work queue before the changes took place will still be sent to the configured endpoint.

Events Delivery Order and Cardinality

Depending on the integration you plan to develop using the Docebo webhooks, you may find yourself needing to manage events in an orderly manner. For example, suppose you want to define a webhook that sends data for creating, modifying and deleting a user.

For these operations, the order in which you receive the events is extremely important. Although Docebo will do everything possible to ensure an orderly delivery, the fault-tolerance system of the implementation does not allow Docebo to absolutely guarantee that the sending of events takes place exactly in the order in which they occurred. Therefore, we suggest implementing a system of events re-establishment before they are actually consumed by your integration.

For the same reasons, it’s also necessary that you are able to discard duplicate events by making your endpoint idempotent, because under certain conditions, the webhook implementation could send the same message several times.

Please note that the sending system queues the messages in real time, but the delivery of the message can be postponed by a variable time due to the quantity of queued items and the throttling system in place. Although Docebo tries to minimize the waiting time before sending, the correct management of postponed messages is the responsibility of the receiver endpoint.

Error Management

The Last External System Error column in a webhook’s row on the main Webhooks page will display only the latest error message received from the external system. A number of various errors can be displayed in the column, but your platform will only display the last error received from the webhook, so it’s your responsibility to understand whether the error displayed is the only error received or if it was the last error of several from the webhook.

Additionally, this column may not always display the error of the last call. This means that the last error will appear there, even if the next calls after the error were successful. Docebo provides you with this error information because it enforces an Exponential Backoff Policy. This means that it has a retry policy in case the call fails, but there is a limit to this policy.

The more frequently that Docebo receives the error from the external system, the longer it delays the retry. This means that after a certain amount of retries (up to 48 hours after the initial call), Docebo will automatically disable the webhook so you can fix the issue with the call, reconfigure the webhook and enable it later.

Note also that a single failure can result in Docebo disabling the webhook without retries. This means that even if the call was successful for 1,000 events but fails repeatedly for one event, Docebo has the right to immediately disable the webhook upon the single failure.

Please see the following information about possible error codes that may be displayed:

– HTTP 200 Response Codes (2xx). Docebo considers the delivery of the call a success, so no retries will be performed.

– HTTP 300 Response Codes (3xx). These error codes generally refer to redirects, so Docebo will follow the redirect and will not consider it as an error. The delivery of the call is considered a success, so no retries will be performed.

– HTTP 400 Response Codes (4xx). Docebo treats all 400 error codes as an error, so Docebo will continue retries throughout the normal Exponential Backoff Policy, but retries will end after the normal cycle if no responses are received. The only exception to this procedure is a 410 error. When a 410 error is received, Docebo will immediately disable the webhook, as it generally means that the endpoint is no longer available.

– HTTP 500 Response Codes (5xx). Upon 500 error codes, Docebo will continue retries throughout the normal Exponential Backoff Policy, but retries will end after the normal cycle if no responses are received.

Please Note: Docebo does not provide support for external errors because the error does not come from the Docebo side, nor does it provide support for misconfigured webhooks. Docebo can only confirm whether or not an HTTP call was sent from the Docebo side.

Payload Notes

Keep in mind that for performance reasons, payloads from Docebo are skinny payloads, meaning that it provides basic information to your Payload URL. If you’re wanting more information, you should refer directly to the payload. You can identify the ID of the updated resources via the webhook, then call back the proper API for updates.

Throttling Notes

For performance reasons, Docebo has put certain technical limits in place to ensure that it doesn’t send too much data to a single endpoint in a specific amount of time.

Please Note: In case your endpoint is not able to handle the amount of data sent by Docebo in a given time, you will receive a 426 response code or other codes. These codes generally mean that everything is in range from Docebo’s side, but your endpoint is not capable of receiving the amount of data sent. When this happens, Docebo will continue retries throughout the normal Exponential Backoff Policy, but retries will end after the normal cycle if no responses are received.