Introduzione

Docebo permette di creare webhook che si attivano quando si verifica un evento nella piattaforma, 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 sistema di Human Capital Management (HCM), inviare email a utenti non presenti in piattaforma riguardo eventi avvenuti in piattaforma, o aggiornare il proprio sistema di Content Storage Management.

Una volta attivata l'app Webhooks in piattaforma, è possibile creare l’input di un evento iniziale in modo che Docebo inserisca i dati relativi all'evento in un messaggio JSON e inviarli tramite una chiamata POST HTTP o HTTPS (non tramite email o notifica) a un determinato URL configurato per il webhook associato all'evento.

È inoltre possibile creare dei webhook attraverso le API messe a disposizione da Docebo. Fare riferimento alla documentazione ufficiale API per ulteriori informazioni. Le funzionalità dei webhook sono costantemente ampliate al fine di includere più integrazioni e più eventi, quindi ricorda di controllare la pagina degli Aggiornamenti di Prodotto (si apre in una nuova tab) per non perderti le novità.

Questo articolo illustra come attivare l'app Webhook, come creare e gestire i webhook, offre informazioni sui payload e i throttle e altre note importanti per l'utilizzo dei webhook in piattaforma. Fare riferimento all'articolo della Knowledge Base relativo agli eventi webhook per esempi di webhook e di eventi, e per la descrizione JSON di ogni evento.

Informazioni Importanti

• Questa app può essere gestita unicamente dai Superadmin. I Power User non possono visualizzare e gestire i webhook.

Attivare l'app Webhook

Attivare l'app Webhook come descritto nell'articolo della Knowledge Base dedicato alla gestione di applicazioni e funzionalità. L'app si trova nella tab Caratteristiche Aggiuntive di Docebo.

Creare, modificare e eliminare webhook

Una volta attivata l'app, è possibile gestirla accedendo al Menu Amministrazione, quindi premendo Gestione nella sezione Webhooks. Dalla pagina Webhook è possibile aggiungere nuovi webhook e gestire quelli esistenti: abilitarli, disabilitarli, modificarli, eliminarli e controllare gli errori provenienti dal sistema esterno (se presenti).

Per aggiungere un webhook, premere il pulsante più in alto a destra.

Nel pannello di destr, assegnare al webhook un nome significativo e nel campo URL Payload inserire l'URL del webhook. Scegliere se si desidera che la piattaforma raggruppi gli eventi. Per ulteriori informazioni sul raggruppamento degli eventi, consultare il capitolo Raccolta payload in questo articolo. Quindi premere Avanti per continuare.

Attenzione! Il tipo di webhook non può essere modificato ed è sempre impostato come HTTP.

Selezionare fino a otto eventi da includere nel webhook nel pannello a scomparsa, quindi premere Crea.

Il nuovo webhook sarà visualizzato nell'elenco della pagina principale Webhook e sarà disattivato di default. Premere il menu ellipsis in fondo alla riga del webhook appena creato. Nel menu a tendina, premere Modifica.

Nella finestra seguente è possibile modificare tutta la configurazione del webhook, fatta eccezione per il tipo. Se è necessario modificare o aggiungere eventi al webhook, cliccare l'icona X nell'area dell'evento per eliminarlo; il pulsante più in fondo all'elenco degli eventi per aggiungere altri eventi utilizzando lo stesso metodo utilizzato per la creazione del webhook. Per maggiori dettagli su ciascun webhook e sui relativi payload in formato JSON, consultare l'articolo relativo agli eventi webhook.

Se si desidera modificare l'URL di destinazione o è necessario abilitare l'autenticazione di base per il webhook, passare alla tab Informazioni endpoint dove è possibile modificare il campo URL Payload o, selezionando l'opzione Abilita autenticazione di base, inserire il nome utente e la password necessari per l'autenticazione di base.

Premere il pulsante Salva le modifiche per finalizzare l'aggiornamento.

Una volta completate tutte le fasi di configurazione, attivare il webhook cliccando il menu ellipsis alla fine della riga del webhook e quindi Attiva dal menu a tendina.

Lo stato del webhook nell'elenco dei webhook diventerà Attivo.

Se, per qualsiasi motivo, è necessario disattivare il webhook, premere il menu ellipsis alla fine della riga del webhook e selezionare Disattiva dal menu a tendina.

Per eliminare un webhook, premere il menu ellipsis alla fine della riga del webhook e selezionare Elimina dal menu a tendina.

Sarà visualizzato un messaggio di conferma. Per confermare l'eliminazione, premere Elimina.

Note sulla creazione dei webhook

• L’URL Payload deve essere un URL HTTP o HTTPS formattato correttamente. È possibile inserire un URL Payload per ogni webhook e fino ad otto eventi per webhook, in modo da inviare le informazioni per più di un evento ricevendo un solo URL Payload.
• Sebbene non ci siano limiti al numero di webhook creati o configurati, per questioni di performance, è possibile avere un massimo di dieci webhook contemporaneamente abilitati in piattaforma. Ogni webhook può includere un massimo di otto eventi. Ricorda queste limitazioni al momento della creazione e dell'attivazione dei webhook.
• Docebo consiglia vivamente l’utilizzo di HTTPS e l’abilitazione dell’autenticazione di base per l’utilizzo dei webhook, in quanto rende più sicure le informazioni che la piattaforma invia all’endpoint.
• Nella gestione della rotazione dell'autenticazione di base e delle password, assicurarsi che le vecchie password restino valide per qualche tempo, in base al proprio traffico. I vecchi messaggi si autenticheranno utilizzando le vecchie password; nel caso in cui queste password non siano più valide, il messaggi falliranno.
• Tenere sempre traccia delle email di notifica relative agli errori di consegna. Se un messaggio non è consegnato entro 60 ore, il webhook sarà disattivato dal sistema e nessun nuovo messaggio sarà inviato dal webhook. I messaggi inviati e ancora in coda prima della disattivazione del webhook saranno comunque inviati.
• Nel caso in cui si preveda un flusso importante di messaggi, separare i webhook in diversi domini (domain1.webhook.com, domain2.webhook.com, ecc.) per assicurarsi che i webhook della piattaforma siano gestiti in code parallele. Questa accortezza non è necessaria per i flussi meno importanti, ma il raggruppamento in code può comunque ottimizzare i tempi di consegna.

Note sulla disattivazione dei webhook

• È possibile attivare fino a dieci webhook alla volta, per un massimo di 80 eventi.
• Quando si disabilita un webhook, ricordare che non potrebbe avvenire immediatamente. I webhook formano una coda di lavoro in Docebo; qualsiasi lavoro ancora in corso o in coda prima delle modifiche sarà comunque inviato all'endpoint configurato.

Note sull'eliminazione dei webhook

• Quando un webhook è eliminato non potrà essere riutilizzato in futuro. Se lo scopo è quello di non eseguire il webhook temporaneamente, utilizzare invece la funzionalità di disattivazione. Prima di eliminare un webhook, accertarsi di aver ricevuto tutte le informazioni necessarie.
• L'eliminazione del webhook non eliminerà i dati precedentemente inviati.

Raccolta payload

Quando si configura o si modifica un webhook, la sezione Raccolta payload permette di definire se raggruppare i payload relativi agli eventi dello stesso tipo e generati dallo stesso processo in un solo messaggio. Ad esempio, quando questa opzione è attiva, se un webhook include l'evento Corso creato e una singola chiamata API crea dieci corsi nella piattaforma, l'endpoint riceverà un unico webhook che include dieci eventi di tipo Corso creato, invece di ricevere dieci messaggi webhook separati, uno per ogni nuovo corso.

Attenzione! L'attivazione di questa opzione non garantisce che il numero di eventi inclusi in una raccolta di payload corrisponda al numero di eventi generati dal processo di attivazione (la chiamata API, nel nostro esempio). Il numero di eventi raccolti nei webhook cambia in base alla logica di ottimizzazione del buffer dell'infrastruttura della piattaforma. Facendo riferimento al nostro esempio, quando la chiamata API attiva la creazione di dieci corsi, in base alla logica di ottimizzazione del buffer, si potrebbe ricevere un webhook che include una raccolta di dieci eventi, due webhook che includono cinque eventi ciascuno o un webhook che raccoglie nove eventi più un webhook a evento singolo.

Quando i webhook includono più di un evento, il payload della proprietà comune del webhook si trasforma in payload, indicando che il messaggio include più eventi. Se la funzione di raccolta dei payload è attiva, assicurarsi che il sistema di endpoint sia pronto a ricevere webhook con due strutture diverse.

Payload dei webhook

Abilitare dati aggiuntivi ai payload

In base alle proprie necessità, potrebbe essere necessario attivare dati aggiuntivi al payload, in modo che le informazioni passate ai sistemi esterni siano più dettagliate. I dati aggiuntivi sono disponibili per i corsi, i webinar, le iscrizioni e i piani formativi. Per abilitare i dati aggiuntivi, contattare l'Help Desk attraverso l'Help Center.

La sezione dei dati aggiuntivi per il payload è identificata come extra_data.

Note sui payload dei webhook

• Per questioni di performance, i payload di Docebo sono leggeri, ovvero forniscono informazioni di base all'URL Payload. Nel caso in cui siano necessarie più informazioni, fare direttamente riferimento al payload. È possibile identificare l'ID delle risorse aggiornate via webhook e chiamare le relative API per gli aggiornamenti.
• I payload dei webhook includono sempre il parametro id, che è lungo 56 caratteri.
• Consigliamo di identificare quali eventi webhook sono scatenati dopo le azioni batch, e di raggrupparne i payload. Quando Docebo Learn esegue un'azione che scatena più eventi dello stesso tipo in un breve lasso di tempo, i webhook inviati possono contenere più payload dello stesso tipo in un solo messaggio. Il raggruppamento riduce il numero di messaggi e permette di consumare più eventi a velocità maggiore.

Ricezione dei webhook

Docebo si aspetta un codice di stato 2xx o 3xx HTTP a conferma della ricezione del webhook. Nel caso di ricezione di codici di stato di errore 4xx o 5xx, l'invio sarà registrato come non riuscito. Anche nel caso in cui Docebo non riceva una risposta entro 5 secondi dall'invio della richiesta, la richiesta sarà considerata e registrata come non riuscita, anche nel caso in cui il server remoto ritardi la risposta perché sta elaborando la richiesta. Fare riferimento all'articolo relativo Gestione degli errori per ulteriori informazioni.

Note sulla ricezione dei webhook

• Invitiamo a rispondere con un messaggio di tipo 200 , nel minor tempo possibile. Il sistema di consegna dei webhook ha un timeout di 5 secondi. Dopo questo lasso di tempo, la consegna sarà considerata fallita, e quindi riprogrammata. Senza un messaggio di ricezione di tipo 200, Docebo non è in grado di verificare che il webhook sia stato ricevuto.
• Al momento della ricezione, è buona pratica salvare il webhook come prima cosa, poi confermarne la ricezione e infine elaborarlo. I webhook possono essere inviati più volte, quindi salvarli ed elaborarli in un secondo momento permette di filtrare i duplicati. Utilizzare fired_at come data e ora dell'evento originale, e l'id del messaggio come identificativo univoco per individuare i duplicati.

Eventi

Gli eventi disponibili nell'app Webhook sono dettagliati in un articolo dedicato della Knowledge Base. 

Webhook e Audit Trail

Se l'app Audit Trail è attiva in piattaforma, è possibile attivare il tracciamento delle azioni che seguono nei report Audit Trail:

Evento Audit Trail	Descrizione dell'evento
Webhook creato	Azione tracciata alla creazione del webhook
Webhook aggiornato	Azione tracciata all’aggiornamento del webhook
Webhook cancellato	Azione tracciata alla cancellazione del webhook
Webhook attivato	Azione tracciata all'attivazione del webhook
Webhook disattivato	Azione tracciata alla disattivazione del webhook
Webhook disattivato dal sistema	Azione tracciata quando un webhook è disattivato automaticamente dal sistema in base alla politica di invio

Maggiori dettagli sull'Audit Trail.

Ordine e cardinalità della consegna degli eventi

In base all’integrazione che si intende sviluppare utilizzando i webhook di Docebo, potrebbe essere necessario gestire gli eventi in base a criteri di ordinamento. Per esempio, pensiamo alla configurazione di un webhook per l’invio di dati per la creazione, la modifica e la cancellazione di un utente.

Per questo tipo di operazioni, l’ordine di ricezione degli eventi è estremamente importante. Sebbene Docebo farà il possibile per assicurare il corretto ordinamento in fase di consegna, il sistema di fault-tolerance dell’implementazione non permette a Docebo di garantire con certezza assoluta che l’invio degli eventi avvenga nell’ordine esatto in cui si sono verificati. Consigliamo quindi di implementare un sistema di riordinamento degli eventi prima che siano effettivamente utilizzati dall’integrazione.

Per lo stesso motivo, è necessario scartare gli eventi duplicati  rendendo l’endpoint idempotente, poiché in alcune circostanze l’implementazione del webhook potrebbe inviare lo stesso messaggio più volte. Per esempio, lo stesso evento potrebbe essere inviato più volte perché la piattaforma attende per cinque secondi una risposta dall'endpoint prima di inviarlo nuovamente. 

Note sull'ordine e sulla cardinalità di consegna

• È buona norma monitorare gli eventi duplicati in piattaforma.
• Il sistema di invio crea code di messaggi in tempo reale, ma la consegna del messaggio può essere ritardata di un tempo variabile in base alla quantità di elementi in coda e dal sistema di throttling in uso.
• Sebbene Docebo cerchi di ridurre al minimo il tempo di attesa prima dell’invio, la gestione corretta delle tempistiche di invio dei messaggi è responsabilità dell’endpoint ricevente.

Throttle dei messaggi

Per questioni di performance, Docebo deve imporre dei limiti tecnici per assicurarsi di non inviare troppi dati ad un singolo endpoint in un determinato periodo. I messaggi sono consegnati approssivamente alla velocità di un messaggio al secondo.