Webhook

I webhook consentono di notificare un destinatario preconfigurato riguardo agli eventi sul portale utilizzando callback http/https. Un utente può configurare i webhook affinché gli eventi sul portale 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 DocSpace.

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

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

Una volta creato e configurato il tuo endpoint, puoi creare webhook in DocSpace. 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 (Stanze, Documenti).
   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 di DocSpace 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 sul portale.
   • URL del payload – un indirizzo dell'endpoint a cui il webhook deve essere inviato.
   • Chiave segreta – imposta una chiave segreta 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 l'hai persa o dimenticata, puoi reimpostarla, ma tutte le integrazioni che utilizzano questa chiave 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.
   • Trigger - 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à del portale come Utenti, Gruppi, Documenti, Cartelle e Stanze. 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 di DocSpace o solo al trigger selezionato/ai trigger selezionati. Riceverai notifiche automatiche sugli eventi di DocSpace 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à di DocSpace modificata.

Puoi disabilitare o riabilitare il webhook creato utilizzando l'interruttore accanto ad esso. Usa l'icona a destra per modificare le impostazioni del webhook specificate durante la sua creazione, visualizzare la cronologia del webhook o eliminare il 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.
• Trigger – il trigger 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.

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 DocSpace, consulta api.onlyoffice.com.