Webhooks - Documentazione - Meta for Developers

Panoramica

I webhook abilitano l'attivazione dell'iscrizione per le app di integrazione personalizzata agli eventi in Workplace e la ricezione degli aggiornamenti in tempo reale. Quando si verifica una modifica in Workplace, il sistema invia una richiesta HTTPS POST a un URL di callback per ogni app di integrazione personalizzata per cui è stata attivata l'iscrizione all'argomento del webhook pertinente.

In tal modo, le app diventano più efficienti, poiché conoscono esattamente il momento in cui si è verificata una modifica e non devono affidarsi alle richieste continue o addirittura periodiche all'API Graph per ottenere i contenuti più recenti.

Il supporto dei webhook per Workplace è fornito dallo stesso framework alla base di Webhooks per Facebook.

Attivazione dell'iscrizione per gli argomenti del webhook

La finestra di dialogo Modifica integrazione personalizzata fornisce le tab per ciascuno degli argomenti del webhook disponibili per le app su Workplace.

La tab Webhook nella finestra di dialogo Modifica integrazione personalizzata

Per aggiungere una nuova iscrizione al webhook su un determinato argomento, fornisci un URL di callback e un token di verifica, quindi seleziona i campi relativi all'iscrizione necessari per la funzionalità che verrà fornita dall'app.

Puoi attivare l'iscrizione di un solo URL per ogni argomento del webhook, ma puoi utilizzare lo stesso URL per più argomenti.

Gestione delle richieste di verifica

Quando aggiungi una nuova iscrizione o ne modifichi una esistente, i server di Facebook effettueranno una richiesta GET all'URL di callback per la verifica della validità del server di callback.

A questo URL verrà aggiunta una stringa di query con i seguenti parametri:

hub.mode: la stringa "subscribe" viene passata in questo parametro
hub.challenge: una stringa casuale
hub.verify_token: il valore verify_token specificato al momento della creazione dell'iscrizione

Durante la ricezione di una richiesta HTTP GET sull'URL di callback, puoi utilizzare il parametro verify_token per convalidare la provenienza della richiesta da un server di Facebook.

Sicurezza dei webhook

Tutte le chiamate del webhook agli URL di callback definiti dallo sviluppatore vengono effettuate tramite HTTPS, garantendo la sicurezza a livello di trasporto per i payload del webhook.

Per garantire una maggiore sicurezza, viene incluso X-Hub-Signature-256 di un'intestazione HTTP in ogni payload POST, che dovresti utilizzare per la verifica della provenienza del payload da un server di Facebook.

Per i dettagli completi di questo comportamento, consulta la documentazione sul framework del webhook di Facebook.

Argomenti del webhook

L'attività su Workplace viene raggruppata in argomenti. Ogni argomento dispone di un numero di campi che mappano gli eventi su un determinato argomento. Le app possono attivare l'iscrizione per gli aggiornamenti del webhook su ogni argomento e per i campi specifici all'interno di ogni argomento.

Al momento, Workplace fornisce i webhook per i seguenti argomenti e gruppi:

Pagina

Per maggiori informazioni, consulta i Documenti di riferimento sull'argomento della Pagina.

Campo relativo all'iscrizione	Comportamento
`mention`	Si attiva quando una pagina di integrazione personalizzata (bot) viene menzionata in un gruppo.
`messages`	Si attiva quando a una pagina di integrazione personalizzata (bot) viene inviato un messaggio su Workplace Chat.
`message_deliveries`	Si attiva quando viene consegnato un messaggio inviato da una Pagina di integrazione personalizzata (bot).
`messaging_postbacks`	Si attiva quando viene premuto un pulsante di postback in Work Chat.
`message_reads`	Si attiva quando un messaggio di una Pagina di integrazione personalizzata (bot) viene letto dal destinatario.

Gruppo

Per maggiori informazioni, consulta i Documenti di riferimento sugli argomenti per i gruppi.

Campo relativo all'iscrizione	Comportamento
`posts`	Si attiva quando viene aggiunto, aggiornato o eliminato un post in un gruppo.
`comments`	Si attiva ogni volta che viene aggiunto, aggiornato o eliminato un nuovo commento in un gruppo.
`membership`	Si attiva quando cambiano i membri di un gruppo.

Utente

Per maggiori informazioni, consulta i Documenti di riferimento sugli argomenti per l'utente.

Campo relativo all'iscrizione	Comportamento
`status`	Si attiva quando un utente pubblica o modifica un aggiornamento di stato sul proprio profilo.
`events`	Si attiva ogni volta che un utente crea, accetta o rifiuta un evento.
`message_sends`	Si attiva ogni volta che un utente invia un messaggio su Workplace Chat.

Link

Per maggiori informazioni, consulta i Documenti sulle anteprime autorizzate.

Campo relativo all'iscrizione	Comportamento
`preview`	Si attiva quando Workplace deve recuperare informazioni su un URL.
`collection`	Rilevante solo per le app presenti nella lista di elementi consentiti che supportano la navigazione gerarchica del riquadro di composizione dei post.

Sicurezza

Per maggiori informazioni, consulta i Documenti di riferimento sugli argomenti relativi alla sicurezza.

`sessions`

Gli eventi si attivano quando una persona accede o esce da Workplace.

Evento Comportamento

Evento	Comportamento
`log_in`	L'utente ha effettuato l'accesso a Workplace con password o SSO, su www o app mobili.
`log_out`	L'utente è uscito da Workplace con password o SSO, su www o app mobili. Non include la disconnessione forzata avviata dall'amministratore (consulta `admin_force_log_out`).

log_in

L'utente ha effettuato l'accesso a Workplace con password o SSO, su www o app mobili.

log_out

L'utente è uscito da Workplace con password o SSO, su www o app mobili.

Non include la disconnessione forzata avviata dall'amministratore (consulta admin_force_log_out).

`passwords`

Gli eventi si attivano quando una persona modifica la propria password o richiede la reimpostazione della password.

Evento	Comportamento
`password_change`	La password di un utente è stata modificata a seguito del completamento del ripristino della password o tramite le impostazioni account.
`password_reset_request`	È stato avviato il flusso di recupero della password di un utente ed è stato inviato un codice all'indirizzo e-mail dell'utente.
`password_reset_wrong_code`	Un utente ha inserito un codice di recupero per la reimpostazione della password errato.
`password_reset_success`	È stato completato correttamente il flusso di recupero della password di un utente.

`admin_activity`

Gli eventi attivati quando un amministratore viene aggiunto o rimosso da una community di Workplace

Evento	Comportamento
`admin_set_to_unclaimed`	Un amministratore ha impostato lo stato dell'account di un utente su unclaimed (non reclamato) dal Pannello di amministrazione o tramite l'API Account Management.
`admin_force_log_out`	Un amministratore ha forzato l'uscita di un utente su tutti i dispositivi dal Pannello di amministrazione.
`admin_deactivate`	Un amministratore ha disattivato un account dal Pannello di amministrazione oppure tramite l'API Account Management.
`admin_activate_account`	Un amministratore ha attivato un account dal Pannello di amministrazione oppure tramite l'API Account Management.
`force_password_reset`	Un amministratore ha forzato la reimpostazione della password di un utente dal Pannello di amministrazione.
`admin_create_account`	Un amministratore ha creato un account dal Pannello di amministrazione.

`two_factor`

Gli eventi attivati quando una persona abilita o disabilita l'autenticazione a due fattori.

Evento	Comportamento
`two_factor_enable`	Un utente ha abilitato l'autenticazione a due fattori dalla tab Impostazioni. Non acquisisce il momento in cui una persona conferma un particolare cellulare, ma indica che la funzione è stata abilitata.
`two_factor_disable`	Un utente ha disabilitato l'autenticazione a due fattori dalla tab Impostazioni. Non acquisisce il momento in cui una persona disabilita un particolare cellulare, ma indica che la funzione è stata disabilitata.