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 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 la 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 in una chiamata POST HTTP o HTTPS (non via email o notifica) ad 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 continueranno ad essere 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 descrive come attivare la 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 la App

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

Creare Webhook

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

Per aggiungere un webhook, premere il pulsante più in alto a destra. Nella pagina di configurazione, accedere alla sezione Generale. Definire il Nome del webhook che sarà utilizzato per identificarlo in piattaforma. Inserire quindi l'URL Payload a cui il webhook invierà informazioni.

Cliccare Seleziona Eventi nella sezione Eventi per aggiungere eventi al webhook. Nel pannello a scomparsa, selezionare un massimo di otto eventi da includere nel webhook, quindi premere Conferma. Il campo Eventi sarà popolato dagli eventi selezionati, ma sarà possibile eliminarli in qualsiasi momento utilizzando l’icona X accanto ad ogni evento. Per ulteriori informazioni riguardo i webhook ed il corrispondente codice JSON, fare riferimento all'articolo dedicato agli eventi webhook della Knowledge Base.

Spostarsi ora alla sezione Autenticazione dove è possibile attivare l’opzione Abilita Autenticazione di Base per l’endpoint di ricezione. Una volta abilitato, sarà possibile inserire lo username e la password di autenticazione di base nei campi corrispondenti della sezione Informazioni Protocollo.

Infine, spostarsi alla sezione Raccolta Payload, dove è possibile raggruppare i payload relativi ad eventi dello stesso tipo e generati dallo stesso processo in un solo messaggio di consegna. Per esempio, quando si abilita questa opzione, se un webhook include l’evento Course Created, a una API crea dieci corsi in piattaforma, l’endpoint riceverà un solo webhook contenente dieci eventi Course Created, invece di dieci messaggi webhook, uno per ogni nuovo corso.

Abilitare questa opzione non garantisce che il numero di eventi inclusi in un gruppo di payload corrisponda al numero di eventi generati dal processo che ha attivato gli eventi (la chiamata API, nel nostro esempio). Il numero di eventi contenuti in un webhook cambia in base alla logica di ottimizzazione del buffer dell’infrastruttura dalla piattaforma. Tornando al nostro esempio, quando la chiamata API attiva la creazione dei dieci corsi, in base alla logica di ottimizzazione del buffer, è possibile ricevere un webhook contenente dieci eventi, due webhook da otto eventi ciascuno, o un webhook contenente nove eventi più un webhook con un solo evento.

Quando i webhook includono più di un evento, la proprietà comune payload diventa payloads, ad indicare che il messaggio include più eventi. Se si abilita la funzionalità di raggruppamento dei payload, assicurarsi che il sistema di endpoint sia pronto a ricevere payload con diverse strutture.

Una volta terminata la configurazione del nuovo webhook, premere Salva le Modifiche per crearlo. Il nuovo webhook sarà visualizzato nell’elenco della pagina principale dei Webhook e sarà disabilitato di default. Fare riferimento alle sezioni corrispondenti in questo articolo per ulteriori informazioni su come disabilitare, riabilitare, modificare o cancellare il webhook.

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 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.
• Mantenere 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.

Payload

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

• 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 nella app Webhook sono dettagliati in un articolo dedicato della Knowledge Base. 

Modificare o Cancellare Webhook

Tutti i webhook sono visualizzati nell’elenco della pagina principale Webhook. È possibile modificare la configurazione dei webhook in qualsiasi momento, premendo l’icona ellipsis nella riga del webhook e selezionare Modifica nel menu a tendina.

Si accederà alla pagina di configurazione del webhook, dove è possibile modificare qualsiasi campo precedentemente configurato, incluso nome, Payload URL, eventi nel webhook e le informazioni di autenticazione di base. Premere Salva Modifiche per confermare le modifiche.

Per cancellare un webhook, cliccare l’icona ellipsis alla fine della riga del webhook e selezionare Cancella dal menu a tendina. Confermare la propria scelta nella finestra pop-up indicando che si desidera procedere e premere Conferma.

Quando un webhook è cancellato, non è più utilizzabile in futuro. Se si desidera semplicemente disabilitare un webhook per un determinato periodo, disattivare il webhook modificandone lo stato. Prima di cancellare un webhook, assicurarsi di aver ricevuto tutte le informazioni necessarie.

Note sulla Modifica e la Cancellazione dei Webhook

• La modifica e la cancellazione di un webhook potrebbero non essere immediate. I webhook formano una coda in Docebo, quindi ciò che è ancora in lavorazione o in coda prima delle modifiche sarà comunque inviato all’endpoint configurato per il webhook nel momento in cui si attiva il webhook.
• La cancellazione di un webhook non cancellerà i dati precedentemente inviati.
• Quando si copia o si sposta di un webhook, il webhook in questione sarà disattivato e sarà necessario attivarlo nuovamente.

Attivare o Disattivare i Webhook

Il check mark nella colonna Stato di ogni webhook, nella pagina principale dei Webhook, permette di visualizzare e modificare i webhook attualmente attivati o disattivati. Un check mark verde indica che il webhook è attivato, mentre un check mark grigio indica che il webhook è disabilitato e che quindi non si attiverà.

Cliccare il checkmark nella riga del webhook per abilitarlo o disabilitarlo.

Note Importanti sulla Disattivazione dei Webhook

• È possibile attivare al massimo dieci webhook alla volta, per un totale di 80 eventi.
• La disattivazione di un webhook di un webhook potrebbe non essere immediata. I webhook formano una coda in Docebo, quindi ciò che è ancora in lavorazione o in coda prima delle modifiche sarà comunque inviato all’endpoint configurato per il webhook.

Webhook e Audit Trail

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

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 la 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.