Introduzione

Docebo permette di creare webhook attivabili su base evento, al fine di inviare informazioni riguardo l’evento stesso ad uno specifico URL di Payload. In questo modo, è possibile utilizzare i dati dalla piattaforma per popolare report e dashboard, gestire integrazioni e altro ancora. È inoltre possibile connettersi al proprio HCM, inviare email a utenti non presenti in piattaforma riguardo eventi avvenuti in piattaforma, o aggiornare il proprio CSM. Ulteriori informazioni sui webhook.

Docebo aspetta un codice di stato 2xx HTTP o 3xx HTTP a conferma della ricezione dei webhook. Negli altri casi, Docebo registrerà l’invio come fallito. Le mancate consegne sono registrate come errori nei log della piattaforma, in modo che sia possibile controllarli e prendere provvedimenti per risolvere la situazione.

Controllare gli Errori

Per controllare gli errori registrati in piattaforma, accedere al Menu Amministrazione, quindi selezionare Gestione nella sezione Webhook. Nella pagina principale dei Webhook, controllare la colonna Ultimo Errore Sistema Esterno nella riga del webhook.

Questa colonna mostra l’ultimo messaggio di errore ricevuto dal sistema esterno. Sebbene la piattaforma potrebbe aver ricevuto più errori, sarà visualizzato solo l’ultimo errore ricevuto dal webhook, quindi è necessario assicurarsi che l’errore visualizzato sia l’unico ricevuto, oppure l’ultimo di una serie di errori.

Questa colonna potrebbe non visualizzare sempre l’errore dell’ultima chiamata. La colonna visualizza l’ultimo errore, anche se dopo l’errore sono state registrate chiamate con esito positivo. Docebo fornisce informazioni riguardo l’errore per conformità alla Exponential Backoff Policy. Questo significa che di in caso di fallimento della chiamata saranno effettuati altri tentativi, ma c’è un limite dettato da questa policy.

Passare il mouse sul codice di errore per visualizzare il timestamp dell’ultimo errore registrato. Queste informazioni forniranno ulteriori dettagli, aiutando a capire meglio cosa è successo. Cliccare sull’icona menu alla fine della riga del webhook e selezionare Reset System Error dal menu a tendina per effettuare un reset del valore visualizzato dalla colonna allo stato di default (nessun errore), per eseguire i test. Quando si seleziona questa opzione, sarà eseguito il reset solo del valore della colonna, l’errore non sarà cancellato.

Cliccare sul nome del webhook e spostarsi alla tab Error Logs per ottenere più dettagli sull’errore. Questa tab elenca tutti gli errori registrati per il webhook selezionato. Potrebbero essere necessari alcuni minuti prima che il sistema carichi tutti gli errori registrati. Cliccare sull’icona filtro in altro a sinistra della tabella per filtrare gli errori per data, range, nome dell’evento o tipo di errore. Il filtro Tipo di Errore mostra solo i codici degli errori effettivamente registrati, non saranno quindi mostrati i codici degli errori non registrati per il payload selezionato.

Per visualizzare il payload che ha generato l’errore, cliccare sul menu ellipsis alla fine della riga dell’URL del payload, e selezionare l’opzione View Payload.

Politica di Rinvio

Dopo l'invio di un webhook, Docebo attende la risposta dell'endpoint per cinque secondi a conferma della ricezione.

In caso di errore o di mancata risposta da parte del sistema esterno, Docebo mapperà i seguenti errori nel log, in base alle circostanze:

Docebo proverà ad inviare nuovamente lo stesso webhook, con lo stesso payload, per 10 volte in 48 ore (a partire dalla prima chiamata), e disabiliterà automaticamente il webhook alla ricezione del decimo errore, in modo che sia possibile risolvere il problema e riconfigurare il webhook, se necessario.

Poiché la ricezione di un messaggio webhook può fallire per diversi motivi (timeout, errore HTTP, host non raggiungibile, ecc.), la piattaforma programmerà un nuovo invio dei messaggi non consegnati in base alle tempistiche indicate nella tabella che segue:

Ogni messaggio è consegnato al massimo 10 volte. Ne risulta che l'ultimo tentativo viene effettuato circa 61 ore dopo il primo tentativo, prima che il messaggio sia scartato e quindi inserito nella Dead Letter Queue (DLQ).

La disattivazione automatica del webhook può essere tracciata grazie alla funzionalità Audit Trail.

Note sulla Politica di Rinvio

• È necessario riattivare il webhook manualmente dopo la disattivazione, non sarà riattivato automaticamente.
• Il numero di errori è conteggiato per ogni payload che compone il webhook. Questo significa che se un solo payload genera 10 errori, tutto il webhook sarà disabilitato. Gli errori dei payload non si sommano. Se, per esempio, il Webhook 1 è attivato da due eventi diversi con due payload diversi, Payload A e Payload B, nel caso in cui il Payload A generasse 8 errori, e il Payload B generasse 2 errori, il webhook non sarebbe disabilitato. Sarà disabilitato solo al raggiungimento del decimo errore di uno dei payload.
• Nel caso in cui l'endpoint non riesca a gestire la mole di dati inviati da Docebo in un determinato periodo, si riceverà una risposta con codice 426, o altri codici ad indicare che non ci sono problemi dal lato Docebo, ma che l'endpoint non è in grado di ricevere la mole di dati inviati. In questo caso, Docebo continuerà a riprovare in base alla politica di Exponential Backoff, ma i tentativi termineranno dopo il ciclo normale in caso di mancata risposta. 

Politica di Conservazione dei Webhook - Dead Letter Queue

I messaggi webhook non consegnati dopo dieci tentativi sono aggiunti alla Dead Letter Queue. È possibile recuperarli tramite ID utilizzando la seguente API (GET):

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

Per cancellare l'elenco, utilizzare invece l'API che segue (DELETE):

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

Maggiori informazioni sul funzionamento di queste API sono disponibili nell'API Browser.

I messaggi nella Dead Letter Queue da più di 60 giorni sono cancellati automaticamente dal sistema.

Codici di Errore

Questo capitolo elenca i possibili codici errore:

Docebo non fornisce supporto per gli errori esterni poiché non sono generati da Docebo. Allo stesso modo, non fornisce supporto per i webhook non correttamente configurati. Docebo può solo confermare se la chiamata HTTP è stata inviata da Docebo.

Abilitare le Notifiche per gli Errori Webhook

I webhook sono utilizzati per processi giornalieri, e attivare le notifiche per i casi di errore può aiutare a gestirli per tempo. Per gestire le notifiche, accedere alla pagina principale della gestione dei Webhook, quindi spostarsi alla tab Notifiche. Abilitare le notifiche con l’opzione dedicata, quindi definire l’elenco dei destinatari. L’elenco dei destinatari accetta solo indirizzi email verificati e associati a utenti di piattaforma. Gli indirizzi email non associati a utenti della piattaforma non sono accettati.

È possibile aggiungere fino a cinque destinatari. Nel caso in cui sia necessario notificare più di cinque destinatari, consigliamo di utilizzare una lista di distribuzione creando un utente di piattaforma a questo scopo, e utilizzare l’email a lui associata come indirizzo per la mailing list. Poiché questo utente non accede corsi o contributi, non sarà considerato un utente attivo della piattaforma, e non avrà impatto sul periodo di fatturazione.

Le notifiche Webhook sono parte della funzionalità di Webhook e non sono gestite dalla App Notifiche, in quanto queste notifiche sono messaggi di sistema a fine tecnico e il contenuto non è modificabile.

La funzionalità di Webhook gestisce due tipi di notifiche:

• Errore Singolo. I destinatari saranno notificati riguardo il codice di errore, la descrizione dell’errore, il webhook che ha generato l’errore, il nome della piattaforma e il dominio in cui è stato registrato l’errore. La struttura di questa notifica è la seguente:

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!

• Errore multiplo e disattivazione del webhook. Il destinatario sarà notificato che un webhook ha ripetutamente generato un errore e sarà disattivato, secondo la Politica di Rinvio descritta in questo articolo. La notifica include il codice di errore, la descrizione dell’errore, il webhook che ha generato l’errore, il nome della piattaforma, il dominio dove si è verificato l’errore, e un messaggio per invitare l’utente a riattivare il webhook manualmente dopo aver risolto l’errore. La struttura di questa notifica è la seguente:

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.