Webhook

Introduzione

I webhook consentono di notificare un destinatario preconfigurato riguardo agli eventi nello spazio di lavoro utilizzando callback http/https. Un utente può configurare i webhook affinché gli eventi nello spazio di lavoro attivino azioni su servizi esterni. Questo approccio può essere utile per sincronizzare e monitorare determinati eventi.

Utilizza i webhook per eseguire azioni personalizzate sul lato di qualsiasi applicazione o sito web che stai utilizzando basandoti su vari eventi in ONLYOFFICE Apps.

Puoi creare e gestire tutti i tuoi webhook, configurarli e consultare la cronologia di ogni webhook per verificarne le prestazioni.

Creare un nuovo webhook

Prima di tutto, è necessario impostare un endpoint per i webhook all'interno del tuo servizio esterno. Questo endpoint sarà utilizzato per ascoltare i webhook dello spazio di lavoro e ricevere notifiche sugli eventi.

Una volta creato e configurato il tuo endpoint, puoi creare webhook nello spazio di lavoro. Per creare un nuovo webhook,

1. Apri la sezione Strumenti per sviluppatori cliccando sul link Strumenti per sviluppatori disponibile nel pannello di sinistra in qualsiasi sezione (File, Stanze, Moduli).

   note

   Per impostazione predefinita, l'accesso alla sezione Strumenti per sviluppatori è abilitato per tutti gli utenti tranne gli ospiti, in modo che qualsiasi utente possa accedere a questa pagina e, di conseguenza, creare i propri webhook. Gli amministratori possono vedere tutti i webhook creati, mentre gli utenti possono vedere solo i propri webhook.

   Gli amministratori possono utilizzare sia il link Strumenti per sviluppatori a sinistra che passare a questa sezione dalle Impostazioni dello spazio di lavoro utilizzando il menu nell'angolo in basso a sinistra, selezionando l'opzione Impostazioni -> Strumenti per sviluppatori.

2. Nei Strumenti per sviluppatori, vai alla sezione Webhook.

3. Clicca sul pulsante Crea webhook.

4. Imposta i parametri necessari:

   

   • Nome del webhook – un nome identificativo per lavorare comodamente con il webhook nello spazio di lavoro.

   • URL del payload – un indirizzo dell'endpoint a cui il webhook deve essere inviato.

   • Chiave segreta – imposta un segreto del webhook che ti consente di verificare le richieste inviate all'URL del payload. Inserisci la tua chiave o clicca su Genera. Nota: non puoi recuperare la tua chiave segreta una volta salvata. Se hai perso o dimenticato questa chiave segreta, apri le impostazioni del webhook e clicca sul link Reimposta chiave per generarne una nuova. Tutte le integrazioni che usano il segreto precedente dovranno essere aggiornate.

     

   • Verifica SSL – per impostazione predefinita, questa opzione è abilitata per verificare i certificati SSL durante la consegna dei payload. Non è consigliato disabilitare questo parametro.

   • Evento che attiva questo webhook - utilizza l'opzione Invia tutto o seleziona il pulsante di opzione Eventi individuali e scegli solo i trigger specifici, ad esempio eventi relativi a modifiche delle entità dello spazio di lavoro come Utenti, Gruppi, File, Cartelle, Stanze, Moduli e Agenti IA. Ad esempio, utente creato, invitato, aggiornato, eliminato, ecc.

   • ID di destinazione - un identificatore di un utente, un gruppo, un file o una cartella che ti consente di monitorare le modifiche di un oggetto.

   

5. L'URL del payload deve rispondere con lo stato 200 a una richiesta http con il metodo HEAD.

6. Clicca sul pulsante Crea.

A seconda delle impostazioni, il webhook creato sarà assegnato a tutti gli eventi dello spazio di lavoro o solo al trigger selezionato/ai trigger selezionati. Riceverai notifiche automatiche sugli eventi dello spazio di lavoro all'interno del tuo servizio esterno. I trigger selezionati durante la creazione di un webhook specifico vengono attivati solo se il proprietario del webhook ha diritti di accesso all'entità modificata dello spazio di lavoro.

Gestione dei webhook

I webhook creati sono elencati con nome, autore, URL del payload e stato. Puoi disabilitare o riabilitare un webhook utilizzando l'interruttore nella colonna Stato. Usa l'icona a destra per aprire il menu contestuale con le seguenti opzioni:

• Impostazioni - modifica le impostazioni del webhook specificate durante la sua creazione.
• Cronologia del webhook - visualizza la cronologia di consegna del webhook.
• Elimina webhook - elimina il webhook.

Clicca sul webhook per visualizzare la cronologia del webhook

Quando visualizzi la cronologia, puoi filtrare i webhook per data di consegna o stato (Non inviato, 2XX, 3XX, 4XX, 5XX). Clicca sul pulsante filtro, scegli i parametri necessari e clicca su Applica.

Puoi selezionare uno o più webhook nell'elenco e utilizzare l'opzione Riprova che appare in alto per ridistribuire i webhook selezionati. Oppure clicca sull'icona accanto al determinato webhook e seleziona l'opzione Riprova nel menu contestuale.

Clicca sull'icona accanto al determinato webhook e seleziona l'opzione Dettagli del webhook nel menu contestuale.

Sono disponibili i seguenti dettagli:

• Stato – uno stato di risposta.
• ID evento – un ID dell'evento.
• Tipo di evento – l'evento che ha causato l'attivazione del webhook.
• Ora dell'evento – una data in cui l'evento si è verificato.
• Ora di consegna – una data in cui la risposta è stata ricevuta dall'endpoint.

Nelle sezioni Richiesta/Risposta, puoi anche visualizzare l'intestazione della richiesta POST, il corpo della richiesta POST, l'intestazione della risposta POST e il corpo della risposta POST. Usa l'icona per copiare l'intestazione o il corpo della richiesta/risposta negli appunti.

Usa l'icona accanto alla didascalia Dettagli del webhook per ridistribuire il webhook.

Dettagli tecnici

Vengono utilizzati i seguenti due servizi per il funzionamento:

1. ASC.Web.Studio fornisce metodi per l'invio di webhook, avvia WorkerService.

   WorkerService – si sottoscrive per ricevere messaggi da un broker (ad esempio, RabbitMQ è utilizzato per impostazione predefinita), che memorizza informazioni sui nuovi webhook in attesa di essere inviati. I messaggi ricevuti dal broker vengono inseriti in una coda, dopodiché la coda viene costantemente interrogata e contatta in modo asincrono ASC.Webhoks.Service per inviare i webhook.

2. ASC.Webhooks.Core fornisce metodi per pubblicare webhook nel database e nel broker di messaggi, nonché metodi per lavorare con il database.

Per ulteriori dettagli sull'API di ONLYOFFICE Apps, consulta api.onlyoffice.com.