Creare e Gestire i Webhook

Creare, gestire e inviare webhook in piattaforma

Ultimo Aggiornamento

25 Settembre 2020

Modulo Docebo

API

Tempo di Lettura

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

Una volta attivata la app Webhooks in piattaforma, è possibile creare l’input di un evento iniziale, in modo che Docebo possa inviare un post all’URL definito nel webhook relativo all’evento. Docebo inserisce i dati relativi all’evento in un messaggio JSON e lo invia attraverso una chiamata HTTP POST (non via email o come notifica).

È inoltre possibile creare dei webhook attraverso un set completo di API webhook messo a disposizione da Docebo. Fare riferimento alla documentazione ufficiale API per ulteriori informazioni. Le funzionalità di webhook saranno estese nel tempo, al fine di includere più integrazioni e più eventi, quindi ricorda di controllare la pagina degli Aggiornamenti di Prodotto per eventuali aggiornamenti.

Per questioni di performance, è possibile abilitare fino ad un massimo di cinque webhook alla volta in piattaforma. Ogni webhook può includere al massimo otto eventi. È importante ricordare queste informazioni al momento della creazione e dell’attivazione dei webhook.

Questo articolo descrive come attivare la app Webhook, come creare e gestire i webhook, gli eventi da includere nei webhook, la descrizione JSON di ogni evento, le informazioni riguardo i payload e i throttle, e altre informazioni necessarie per utilizzare correttamente i webhook in piattaforma.

La app Webhook è disponibile solo per i clienti Enterprise, e può essere gestita unicamente dai Superadmin. I Power User non possono visualizzare e gestire i webhook.

Attivare la App

Connettersi alla piattaforma come Superadmin, accedere al Menu Amministrazione dall’icona ingranaggio in alto a destra e selezionare Aggiungi Nuove Applicazioni nella parte superiore del menu. Da questa pagina, selezionare Caratteristiche Aggiuntive di Docebo dal menu di sinistra. Identificare la app nell’elenco e premere Provala Gratuitamente. Leggere la descrizione nella finestra pop-up quindi premere di nuovo Provala Gratuitamente. Ora la App è attiva in piattaforma.

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 in piattaforma per identificarlo facilmente. Inserire quindi il URL Payload a cui saranno inviate le informazioni dal webhook.

L’URL del Payload deve essere un URL HTTP/S 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.

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. Per ulteriori informazioni riguardo i webhook ed il corrispondente codice JSON, fare riferimento a questo articolo. Il campo Eventi sarà quindi popolato con gli eventi selezionati, ma sarà possibile eliminarli in qualsiasi momento utilizzando l’icona X accanto ad ogni evento.

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.

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.

Infine, spostarsi alla sezione Payload Collection, dove è possibile definire se 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 piattafora, l’endpoint riceverà un solo webhook contenente dievi eventi Course Created, invece di dieci messaggi webhook, uno per ogni nuovo corso.

Abilitare questa opzione non gatantisce 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 cinque 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 funzionalita 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, ri-abilitare, modificare o cancellare il webhook.

Conferma di Ricezione dei Webhook

Docebo si aspetta un codice di stato 2xx HTTP o 3xx HTTP a conferma della ricezione del webhook. Negli altri casi, Docebo registrerà l’invio come fallito. Fare riferimento all’articolo relativo Gestione degli Errori per ulteriori informazioni.

Abilitare Dati Aggiuntivi per il Payload

In base alle necessità, potrebbe essere necessario attivare dati aggiuntivi per il 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 il proprio Customer Success Manager o Docebo attraverso il Centro Comunicazioni

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

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 sarà 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. La cancellazione di un webhook non cancellerà i dati precedentemente inviati.

Nota importante riguardo la modifica o 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.

Abilitare o Disabilitare i Webhook

Il check mark nella colonna Stato di ogni webhook, nella pagina principale dei Webhook, permette di visualizzare e modificare i webhook attualmente abilitati o disabilitati. Un check mark verde indica che il webhook è abilitato, 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. Ricorda che è possibile abilitare al massimo cinque webhook alla volta.

Nota importante riguardo la disabilitazione dei webhook: la disabilitazione 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:

  • 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 abilitato – Azione tracciata all’abilitazione del webhook
  • Webhook disabilitato – Azione tracciata alla disabilitazione manuale del webhook
  • Webhook disabilitato dal sistema – Azione tracciata quando un webhook è disabilitato automaticamente dal sistema in base alla politica di invio definita qui

Maggiori dettagli sui report 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. E’ buona norma monitorare gli eventi duplicati in piattaforma.

Attenzione, 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.

Note Relative ai Payload

Per motivi di sicurezza, i payload di Docebo sono sono leggeri, ovvero forniscono solo le informazioni di base all’URL di Payload. Nel caso in cui siano necessarie più informazioni, fare riferimento direttamente al payload. È possibile identificare l’ID delle risorse aggiornate attraverso il webhook, quindi richiamare l’API corretta per gli aggiornamenti.

Note Relative ai Throttle

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.

Attenzione: nel caso in cui l’endpoint non riesca a gestire la mole di dati inviata in un determinato periodo da Docebo, si riceverà il codice di risposta 429, o altri codici. Questi codici indicano che non ci si registrano problemi per Docebo, ma l’endpoint non è in grado di ricevere la mole di dati inviata. In questi casi, Docebo continuerà ad effettuare tentativi in base alla Exponential Backoff Policy. I tentativi termineranno dopo il ciclo normale in caso di mancata risposta.