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. Learn more about 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. Failures are recorded as errors in the platform log so that you can check them and take action.

Checking errors

In order to check any webhook error recorded in your platform, access the Admin menu, then press the Manage item in the Webhooks section. On the main Webhooks page, check the Last external system error column in the webhook rows.

This column displays the latest error message received from the external system. Even if the platform received many error messages,  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.

Hover your mouse on the error code to see the timestamp of the last recorded error, this information will provide you with extra details, helping you to better understand what is going on.

Click on the ellipsis menu at the end of the webhook row and select Reset system error from the dropdown menu to reset the column value to the default status (no errors), to carry out your tests. Please note that when selecting this option, only the column value is updated, the error is not erased.

Click on the webhook name and move to the Error logs tab to access a more detailed view of the recorded errors. This tab lists all of the errors recorded for the selected webhook, please note that it may take some minutes before the system loads all of the available errors. Use the search functionality to search a text in any of the available columns.

Click on the filter icon in the top left corner of the table to filter the displayed errors by date range, event name or error type. Please note that the Error Type filter only lists the error codes actually recorded, if an error code has not been recorded for the selected payload, it will not be listed in the Filters area.

In order to view the payload generating the error, click on the ellipsis menu at the end of the row of the payload URL and select the View payload option.

Retry policy

After sending a webhook, Docebo waits for five seconds for an answer from the endpoint in order to acknowledge its receipt. 

In case of errors or lack of response from the external system, Docebo will add the following messages to the error log, depending on the circumstances:

Docebo will retry sending the webhook, with the same payload, 10 times (after the first call) and will automatically disable the webhook upon receiving the 10th error, so that you can fix the issue with the call and reconfigure the webhook, if needed.

Tip: Remember, you have to reactivate the webhook manually after it has been deactivated, it will not be reactivated automatically.

Since the delivery of a webhook message can fail for a number of reasons (timeouts, http errors, the host being unreachable, etc.), a message that fails to be delivered is rescheduled and delivered again. 

Webhooks are re-sent according to the following timing schedule:

Each message is delivered at most 10 times, resulting in the last retry occurring just over 61 hours after the first attempt, before being discarded. When a message is discarded, it is put into a Dead Letter Queue (DLQ).

Tip: The webhook error counter is based on each payload composing the webhook. This means that if a single payload generates 10 errors, the whole webhook will be disabled. Remember that payload errors are not combined. If, for example, Webhook 1 gets fired by two different events with Payload A and Payload B, when Payload A generates 8 errors, and Payload B generates 2 errors, the webhook is not disabled. It will be disabled only when either Payload A or Payload B reaches the 10th error.

The webhook automatic deactivation can be tracked by the Audit trail function.

Please note: In case your endpoint cannot 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.

Webhook retention policy - Dead letter queue

Webhook messages that have failed after ten retry attempts are added to the Dead Letter Queue and can be retrieved, by their ID, via the following GET API call:

/notifications/v1/webhooks/{webhook_id}/dlq

This list can be deleted by issuing the following DELETE API call:

/notifications/v1/webhooks/{payload_ids}/dlq/batch

Please see the documentation in your API Browser for more information on how these endpoints work and how to call them.

Please note: When a message is stored on the Dead Letter Queue and is 60 days old, the webhook message is automatically deleted from the system.

Error codes

This chapter lists the possible error codes that may be recorded by the system:

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.

Enabling notifications for webhooks errors

Webhooks are used for daily processes, and activating notifications when errors occur can help you in managing them promptly. To manage notifications, access the Webhooks page, then move to the Notifications tab. Enable notifications by checking the dedicated option, then set the recipient list. The recipient list accepts verified email addresses associated with a platform user. Email addresses not associated to a platform user are not allowed.

You can add up to five recipients. If you need to notify more than five recipients, we suggest using a distribution list by creating a platform user for this purpose, using the associated email address as a mailing list address. Since this user will not access courses or assets, it will not be considered as an active user in the platform, and will not have an impact on the billing period.

Please note: Webhook notifications are embedded into the webhook functionality. They are not managed by the Docebo Notification app because these notifications are system messages with a technical purpose and their content does not need to be handled.

The webhook functionality manages two types of notifications:

• Single error
  The recipient will be notified about the error code, the error description, the webhook generating the error, the platform name and the domain where the error occurred. This notification is structured as follows:

  Subject: HEADS UP! Webhook endpoint in error!
  
  Hi,
  
  We want to inform you that the endpoint configured for the "[webhook_name]" 
  webhook of the platform "[domain]", has generated the following error: 
  "[error_code][error_description]".
  
  Please check it out!

• Repeated error and webhook deactivation
  The recipient will be notified that a webhook has repeatedly generated an error, and will thus be deactivated, according to the Retry Policy described in this article. The notification includes the error code, the error description, the webhook generating the error, the platform name and the domain where the error occurred and a message to prompt the user to reactivate the webhook manually after the error has been fixed. This notification is structured as follows:

  Subject: HEADS UP! Webhook deactivated in your <platform_name> platform! 
  
  Hi, We want to inform you that the endpoint configured for the "[webhook_name]" 
  webhook of the platform "[domain]", has repeatedly generated the following 
  error: "[error_code][error_description]", and Docebo has deactivated it.  
  
  Please check it out and reactivate the webhook when the problem is solved.