Webhook

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 al relativo argomento del webhook.

In tal modo, le app risultano più efficienti, poiché conoscono esattamente il momento in cui si verifica una modifica, e non devono fare affidamento su 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 API Graph.

Attivazione dell'iscrizione agli 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 sezione 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.

Gestione delle richieste di verifica

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

Una stringa della query verrà aggiunta a questo URL 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

Ogni volta che l'endpoint riceve una richiesta di verifica, deve:

• verificare che il valore hub.verify_token corrisponda alla stringa impostata nel campo Verifica token in fase di configurazione del webhook;
• rispondere con il valore hub.challenge.

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

Per i dettagli completi di questo comportamento, consulta la documentazione sul framework 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.

Attivazione dell'iscrizione ai webhook tramite una chiamata API

Le chiamate API per leggere o modificare le iscrizioni ai webhook devono essere effettuate usando un token dell'app piuttosto che il consueto token dell'integrazione personalizzata. È possibile generare un token dell'app concatenando l'ID dell'app, il simbolo '|' e la chiave segreta.

Ad esempio:

Ottieni le iscrizioni attive ai webhook (usando il token dell'app)

GET graph.facebook.com
  /{app-id}/subscriptions
    &access_token={your_app_token}

Aggiungi una nuova iscrizione webhook (usando il token dell'app)

POST graph.facebook.com
  /{app-id}/subscriptions
    ?object=page
    &fields=mention,messages
    &callback_url={your-url}
    &verify_token={your-verify-token}
    &access_token={your_app_token}

Risoluzione dei problemi della Pagina/Iscrizioni dell'app

Nel caso in cui i webhook non vengano ricevuti come previsto, è consigliabile controllare che l'iscrizione tra la pagina e l'app sia configurata correttamente. La configurazione dovrebbe essere automatica, ma in alcuni casi potrebbero esserci dei problemi. Ad esempio, in caso di errore con la consegna dei webhook per un periodo prolungato, l'iscrizione può essere rimossa. Per le app di terzi, questo comporterà la generazione di un avviso nella Dashboard gestione app.

Per controllare l'iscrizione, sono disponibili le seguenti chiamate API:

Ottieni l'iscrizione dell'app/della pagina corrente (usando il token della pagina)

GET graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}

Per creare nuovamente l'iscrizione, sono disponibili le seguenti chiamate API:

Crea di nuovo l'iscrizione dell'app/della pagina corrente (usando il token della pagina)

POST graph.facebook.com
  /me/subscribed_apps?access_token={your_page_token}
	{"subscribed_fields": ["messages"...]}

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.

Gruppi

Per maggiori informazioni, consulta i Documenti di riferimento sull'argomento del gruppo.

Utente

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

Sicurezza

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

admin_activity

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

compromised_credentials

Gli eventi attivati quando si sospetta che le password di Workplace di alcuni account utente in una community possano essere a rischio.

files

Gli eventi attivati quando si rileva attività relativa ai file su Workplace.

groups

Gli eventi attivati quando una persona crea o si unisce a un gruppo per più aziende in Workplace.

integrations

Gli eventi attivati quando un amministratore crea o modifica le proprietà di un'integrazione.

invites

Gli eventi attivati quando una persona si unisce a Workplace tramite invito automatico.

passwords

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

sessions

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

two_factor

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

reseller_events

Eventi correlati a un rivenditore.

Link

Per maggiori informazioni, consulta i Documenti di riferimento sull'argomento dei link.

Area risorse

Per maggiori informazioni, consulta i Documenti sull'API Graph relativi alle categorie dell'Area risorse.