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, for example, also connect to your human capital management system (HCM), email non-Docebo Learn users about actions that occur within the platform or update your content storage management.

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

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 webhook functionality will be expanded over time to include various integrations and additional events. Please refer to the Product updates page for more information.

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

Tip: This app can only be managed by Superadmins. Power Users have no permissions to view or manage webhooks.

Activating the Webhooks app

Activate the Webhooks app as described in the Managing apps and features article of the Knowledge Base. The app is listed in the Docebo Additional Features tab.

Creating and editing 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 external system errors, if existing.

To add a webhook, press the plus button in the top right corner of the page.

Depending on the type of webhook you wish to create, the process in the following panel will differ as follows:

HTTP and HTTPS webhooks

In the resulting panel, give your webhook a meaningful name, select HTTP for the type of webhook and in the Payload URL field, enter the URL of the webhook. You can also choose if you would like your platform to group events. For more information on grouping events, please see the Payload collection chapter in this article. Then press Next to continue.

Please note: The type of webhook can not be changed once the selection has been made and the webhook has been saved. If you choose the wrong type here, you will need to re-create the webhook again.

SQS webhooks

Tip: The availability of this type of webhook is dependent on your pricing plan.

In the resulting panel, give your webhook a meaningful name, select SQS for the type of webhook and in the ARN field, enter the ARN address of the webhook. Please note that you can not change the region parameter. Next, press the copy icon in the Authentication section to copy the account ID to your clipboard. You will need to grant this ID permission to push events in your system. You can also choose if you would like your platform to group events. For more information on grouping events, please see the Payload collection chapter in this article. Then, press Next to continue.

Please note: The type of webhook can not be changed once the selection has been made and the webhook has been saved. If you choose the wrong type here, you will need to re-create the webhook again.

EventBridge webhooks

Tip: The availability of this type of webhook is dependent on your pricing plan.

In the resulting panel, give your webhook a meaningful name, select EventBridge for the type of webhook and in the ARN field, enter the ARN of the webhook. Please note that you can not change the region parameter. Next, press the copy icon in the Authentication section to copy the account ID to your clipboard. You will need to grant this ID permission to push events in your system. You can also choose if you would like your platform to group events. For more information on grouping events, please see the Payload collection chapter in this article. Then, press Next to continue.

Please note: The type of webhook can not be changed once the selection has been made and the webhook has been saved. If you choose the wrong type here, you will need to re-create the webhook again.

Next, in the panel, you can select up to eight events to include in the webhook, then press Create.

The new webhook will be displayed in the list on the main Webhooks page and will be disabled by default. Next, press the ellipsis menu at the end of the row where your newly created webhook is listed. In the resulting drop-down menu, press Edit.

In the following window, you will be able to edit all aspects of the webhook except for the type of webhook. If you need to change or add events to the webhook, you can press the X icon in each individual event to delete the selected event, alternatively, you can press the plus button at the end of the Events list to add events using the same method as when you first created the webhook. More details on each webhook and the corresponding JSON formatted payloads for them can be found in the Webhooks events article.

If you wish to change the destination URL or, in the event of an HTTP/S webhook, need to enable basic authentication for your webhook, press the Endpoint Info tab. There, in the resulting screen, you can edit the Payload URL field or, by checking the Enable Basic Auth checkbox, you can enter the username and password needed for basic authentication.

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

When you have finished making your changes, press the Save Changes button.

Next, after all the configuration steps have been completed, you can enable the webhook by pressing the ellipsis menu at the end of the row of the corresponding webhook and in the resulting drop-down menu, press Activate.

You will notice that the status of the webhook in your lists of webhooks has been changed to Active.

Please note:

• The Payload URL field must be a properly formatted HTTP URL, HTTPS URL, SQS address or EventBridge address. 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.
• While there is no limit on how many Webhooks you create or configure, for performance reasons, you can have up to a maximum of ten webhooks enabled in your platform at any one time. Keep this in mind when creating and enabling your webhooks.
• When dealing with basic auth and password rotation be sure to allow the old password to remain valid for some time, depending on your traffic. Old messages will authenticate using the old passwords; if you do not accept that password anymore those messages will fail.
• Always keep track of notification emails for delivery errors. If a single message fails to deliver during a 60 hour period, the webhook will be deactivated by the system. It means that no new messages will be sent by this webhook. Messages sent before the webhook was deactivated that are still in the queue will be delivered.
• Separate your webhooks on different domains (domain1.webhook.com, domain2.webhook.com, etc.) to ensure that webhooks for your platform will be managed by parallel queues if you expect a high rate of messages. While this is not necessary for low volume traffic, grouping them on different queues can optimize delivery times.
• Please note that Docebo does not support FIFO queues and does not accept .fifo addresses in the ARN field when creating a webhook.

Deactivating webhooks

If you need to deactivate the webhook, simply press the ellipsis menu at the end of the row of the webhook and, in the resulting drop-down menu, select Deactivate.

Please note:

• You can only have up to ten webhooks enabled at a time, for a maximum of 80 events
• When you deactivate a webhook, keep in mind that the change may not take place immediately. Webhooks form a work queue at Docebo; any work that is still running or in the work queue before the changes took place will still be sent to the configured endpoint.

Deleting webhooks

If you wish to delete your webhook, simply press the ellipsis button at the end of the row of the webhook you wish to delete and in the resulting drop-down menu, press Delete.

You will then be presented with a confirmation message. To confirm the deletion, press the Delete button.

Please note:

• 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 deactivate 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.
• Deleting the webhook will not delete any data that you previously sent.
• When you delete a webhook, keep in mind that the change may not take place immediately. Webhooks form a work queue at Docebo; any work that is still running or in the work queue before the changes took place will still be sent to the configured endpoint.

Webhook payloads

Payload collection

When configuring or editing your webhook, the Payload Collection section is where you can define whether to group the payloads related to the events of the same type and generated by the same process in a single message delivery. For example, when this option is enabled, if a webhook includes the Course Created event, and a single API call creates ten courses in the platform, the endpoint will receive a single webhook including ten Course Created events, instead of receiving ten separate webhook messages, one for each new course.

Please note: Enabling this option does not guarantee that the number of events included in a payload collection corresponds to the number of events generated by the triggering process (the API call, in our example). The number of events collected in webhooks changes depending on the platform infrastructure buffer optimization logic. Referring back to our example, when the API call triggers the creation of ten courses, depending on the buffer optimization logic, you may receive one webhook including a collection of ten events, two webhooks including eight events each, or a webhook collecting nine events plus a single-event webhook.

When webhooks include more than one event, the webhook common property payload turns into payloads, indicating that the message includes more events.

Best practice: If you enable the payload collection feature, make sure that your endpoint system is ready to receive webhooks with two different structures.

Once you’ve finished configuring your webhook, press the Save Changes button.

Enabling extra data for the payload

Depending on your needs, you may want to activate extra data for the payload. This will cause the information passed to external systems to be more detailed. Extra data is available for courses, webinars, enrollments and learning plans. If you are interested in activating extra data, reach out to the Help Desk via the Help Center.

The extra data section of the payload is identified as extra_data.

Please note:

• Keep in mind that for performance reasons, payloads from Docebo are skinny payloads, meaning they provide basic information to your Payload URL. If you want 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.
• The Webhooks payloads always include an id parameter which is 56 characters long.
• Identify which webhooks events may happen after batch actions and enable grouped payloads on those. When Docebo Learn does an intensive action that triggers multiple events of the same type in a very short time, the webhook sent can contain multiple payloads of the same event type in one message. This ensures that there are fewer messages to deliver providing you with the ability to consume more events at a higher rate.

Responding to webhooks

To acknowledge the receipt of a webhook, Docebo expects a 2xx or 3xx HTTP status code to be returned. Receipt of a 4xx or 5xx error status code will result in the sending being logged as a failure. Please also note that if Docebo does not receive a response within 5 seconds of the request being sent, the request is considered to be, and logged as, a failure, even if the remote server may be processing the request but simply has not responded in a timely manner. Please refer to the Error management article for more information.

Webhooks events

Events are described in detail in a dedicated article of our Knowledge Base.

Webhooks and Audit trail

With the Audit Trail functionality, you can track the following actions related to webhooks in your Audit Trail reports:

Audit Trail event	Event description
Webhook created	Action logged when a webhook is created
Webhook updated	Action logged when a webhook is updated
Webhook deleted	Action logged when a webhook is deleted
Webhook enabled	Action logged when a webhook is enabled
Webhook disabled	Action logged when a webhook is disabled manually
Webhook disabled by the system	Action logged when a webhook is automatically disabled by the system according to the Retry Policy defined here

Further details on the Audit trail report.

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, 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 is also necessary that you can discard duplicate events by making your endpoint idempotent because, under certain conditions, the webhook implementation could send the same message several times. As an example, the same event could be sent multiple times because the platform waits for 5 seconds for an answer from the endpoint before sending it again.

Please note:

• Make sure you are monitoring duplicated events in your platform.
• While the sending system queues the messages in real time, it is possible that the delivery of the message may 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.

Throttling of messages

For performance reasons, Docebo has put certain technical limits in place to ensure that it does not send too much data to a single endpoint in a specific amount of time. Messages are dispatched at a rate of approximately one message per second.

Important notes about SQS and Eventbridge webhooks

Webhook logs

When the integrator doesn’t respond (or the ARN destination has not been set properly), errors will be tracked on our current error log. Only errors available via the user interface are tracked in the log or sent via email notifications.

Retry policy

If the webhook is, for any reason, not able to receive the message (for example due to a wrong queue address or credentials), Docebo, after the first attempt, will retry sending the event for another 5 minutes at a rate of 1 attempt per minute. If all retry attempts fail, the webhook will be automatically deactivated.

Dead Letter Queue

If the retry policy reaches the maximum number of sending attempts, the webhook will be stored on a temporary Docebo repository. The repository is encrypted and access to the logs can be gained using the dedicated API. for more information please see Webhooks: Error management.

Retention policy

The message will be stored for 60 days. After that time, the message is permanently deleted.