Webhook: Gestione degli Errori

Gestire gli errori generati dall’invio di payload

Ultimo Aggiornamento

25 Settembre 2020

Modulo Docebo

API

Tempo di Lettura

5 min

Livello Utente

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 Re-Invio

Dopo l’invio di un webhook, Docebo attende la risposta dell’endpoint per cinque secondi, a conferma della corretta ricezione. In caso di errore, o di mancata risposta da parte del sistema esterno, 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. È necessario riattivare il webhook manualmente dopo la disattivazione, non sarà riattivato automaticamente. 

Il contatore degli errori si basa su 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 sono sommati. Se, per esempio, il Webhook 1 è attivato da due eventi diversi con due payload, 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 quando uno dei due payload registra il decimo errore.

La disattivazione automatica del webhook può essere tracciata grazie alla App Audit Trail, se attiva in piattaforma.

Codici di Errore

Questo capitolo elenca i possibili codici errore:

Codici di Risposta HTTP 200 (2xx). Per Docebo la chiamata ha esito positivo, non saranno effettuati ulteriori tentativi di chiamata.

Codici di Risposta HTTP 300 (3xx). Questi codici di errore fanno riferimento a reindirizzamenti, e non sono considerati errori. L’esito della chiamata è considerato positivo, quindi non saranno eseguiti ulteriori tentativi.

Codici di Risposta HTTP 400 (4xx). Docebo considera tutti i codici di errore 400 come errore, quindi effettuerà dei tentativi in base alla Exponential Backoff Policy. I tentativi termineranno dopo il ciclo normale in mancanza di risposta. L’unica eccezione a questa procedura è l’errore 410. In caso di ricezione di questo errore, Docebo disabiliterà immediatamente il webhook, poiché generalmente indica che l’endpoint non è più disponibile.

Codici di Risposta HTTP 500  (5xx). In caso di errore 500, Docebo effettuerà dei tentativi in base alla Exponential Backoff Policy. I tentativi termineranno dopo il ciclo normale in caso di mancata risposta.

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 prontamente. 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 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 Re-Invio 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 e 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.