Primi passi

Questo documento spiega come configurare un webhook che ti informerà ogni volta che gli utenti dell'app pubblicheranno delle modifiche alle proprie foto. Dopo aver compreso come configurare questo webhook, saprai come configurare anche tutti gli altri webhook.

La configurazione di qualsiasi webhook richiede di eseguire i seguenti passaggi:

Creazione di un endpoint su un server sicuro in grado di elaborare richieste HTTPS.
Configurazione del prodotto Webhooks nella Dashboard gestione app della tua app.

Questi passaggi sono spiegati in modo dettagliato di seguito.

Creazione di un endpoint

L'endpoint deve essere in grado di elaborare due tipi di richieste HTTPS: Richieste di verifica e Notifiche per l'evento. Poiché entrambe le richieste utilizzano HTTPs, il server deve disporre di un certificato TLS o SSL valido configurato e installato in modo corretto. I certificati autofirmati non sono supportati.

Le sezioni seguenti spiegano cosa sarà incluso in ogni tipo di richiesta e come rispondere. In alternativa, puoi utilizzare la nostra app di esempio, già configurata per elaborare queste richieste.

Richieste di verifica

Ogni volta che configuri il prodotto Webhooks nella Dashboard gestione app, verrà inviata una richiesta GET all'URL dell'endpoint. Le richieste di verifica includono i seguenti parametri della stringa di query, aggiunti alla fine dell'URL dell'endpoint. Tali parametri saranno simili ai seguenti:

Esempio di richiesta di verifica

GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.challenge=1158201444& hub.verify_token=meatyhamhock

Parametro	Valore di esempio	Descrizione
`hub.mode`	`subscribe`	Questo valore sarà sempre impostato su `subscribe`.
`hub.challenge`	`1158201444`	Un `int` che devi trasmetterci.
`hub.verify_token`	`meatyhamhock`	Una stringa acquisita dal campo Token di verifica nella Dashboard gestione app. Imposti questa stringa al completamento dei passaggi delle impostazioni di configurazione dei webhook.

Nota:PHP converte punti (.) in trattini bassi (_) nei nomi dei parametri.

Convalida delle richieste di verifica

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

verificare che il valore hub.verify_token corrisponda alla stringa impostata nel campo Token di verifica quando configuri il prodotto Webhooks nella Dashboard gestione app (non hai ancora impostato questa stringa del token);
rispondere con il valore hub.challenge.

Se ti trovi nella Dashboard gestione app e stai configurando il prodotto Webhooks (e, quindi, attivi una richiesta di verifica), la dashboard indicherà se l'endpoint ha convalidato la richiesta in modo corretto. Se stai utilizzando l'endpoint /app/subscriptions dell'API Graph per la configurazione del prodotto Webhooks, l'API indicherà con una risposta se l'azione è stata eseguita correttamente o meno.

Notifiche per l'evento

Quando configuri il tuo prodotto Webhooks, attiverai l'iscrizione a fields specifici su un tipo object (ad es., il campo photos sull'oggetto user). Ogni volta che modifichi uno di questi campi, inviamo all'endpoint una richiesta POST con un payload JSON che descrive la modifica.

Ad esempio, se hai richiesto di attivare l'iscrizione al campo photos dell'oggetto user e uno degli utenti della tua app ha pubblicato una foto, ti verrà inviata una richiesta POST simile alla seguente:

POST / HTTPS/1.1 Host: your-clever-domain-name.com/webhooks Content-Type: application/json X-Hub-Signature-256: sha256={super-long-SHA256-signature} Content-Length: 311 { "entry": [ { "time": 1520383571, "changes": [ { "field": "photos", "value": { "verb": "update", "object_id": "10211885744794461" } } ], "id": "10210299214172187", "uid": "10210299214172187" } ], "object": "user" }

Contenuti dei payload

I payload conterranno un oggetto che descrive la modifica. Quando configuri il prodotto Webhooks, puoi indicare se i payload devono contenere solo i nomi dei campi modificati o se i payload devono includere anche i nuovi valori.

Tutti i payload vengono formattati con JSON, quindi puoi analizzare il payload utilizzando i metodi o i pacchetti di analisi comuni JSON.

Non viene memorizzato alcun dato sulle notifiche per l'evento del webhook inviate, quindi assicurati di acquisire e memorizzare i contenuti dei payload che desideri conservare.

La maggior parte dei payload conterrà le seguenti proprietà comuni, ma i contenuti e la struttura di ciascun payload variano a seconda dei campi dell'oggetto per i quali hai attivato l'iscrizione. Consulta il documento di riferimento di ciascun oggetto per vedere quali campi saranno inclusi.

Proprietà	Descrizione	Tipo
`object`	Il tipo di oggetto (ad es. `user`, `page` ecc.)	`string`
`entry`	Un array contenente un oggetto che descrive le modifiche. È possibile raggruppare più modifiche di oggetti diversi dello stesso tipo.	`array`
`id`	L'ID dell'oggetto.	`string`
`changed_fields`	Un array di stringhe che indicano i nomi dei campi che sono stati modificati. Incluso solo se disabiliti l'impostazione Includi valori durante la configurazione del prodotto Webhooks nella Dashboard gestione app della tua app.	`array`
`changes`	Un array contenente un oggetto che descrive i campi modificati e i loro nuovi valori. Incluso solo se abiliti l'impostazione Includi valori durante la configurazione del prodotto Webhooks nella Dashboard gestione app della tua app.	`array`
`time`	Un'indicazione temporale UNIX che indica quando è stata inviata la notifica per l'evento (non quando si è verificata la modifica che ha attivato la notifica).	`int`

Convalida dei payload

Tutti i payload di notifica per l'evento vengono firmati con una firma SHA256 e includono la firma nell'intestazione X-Hub-Signature della richiesta, preceduta da sha1=. Dovresti convalidare il payload, anche se non è obbligatorio.

Per convalidare il payload:

Genera una firma SHA1 utilizzando il payload e la chiave segreta dell'app.
Confronta la tua firma con quella presente nell'intestazione X-Hub-Signature-256 (tutto ciò che si trova dopo sha256=). Se le firme corrispondono, il payload è autentico.

Risposta a notifiche per l'evento

L'endpoint dovrebbe rispondere a tutte le notifiche per l'evento con 200 OK HTTPS.

Frequenza

Le notifiche per l'evento vengono aggregate e inviate in batch con un massimo di 1000 aggiornamenti. Tuttavia non è possibile garantire le operazioni in batch, pertanto assicurati di impostare i server affinché possano gestire singolarmente ogni webhook.

Se l'invio degli aggiornamenti al server non va a buon fine, proveremo immediatamente un nuovo invio, proseguendo con frequenza decrescente per le successive 36 ore. In questi casi, il tuo server deve gestire la deduplicazione. Le risposte non confermate vengono eliminate dopo 36 ore.

Nota: la frequenza con cui vengono inviate le notifiche per l'evento di Messenger è diversa. Fai riferimento alla documentazione sui webhook della Piattaforma Messenger per ulteriori informazioni.

Configurazione del prodotto Webhooks

Quando l'endpoint o l'app di esempio saranno pronti, utilizza la Dashboard gestione app della tua app per aggiungere e configurare il prodotto Webhooks. Puoi anche eseguire la stessa operazione a livello di codice usando l'endpoint /{app-id}/subscriptions per tutti i webhook ad eccezione di Instagram.

In questo esempio, utilizzeremo la dashboard per configurare un webhook che attiva l'iscrizione per qualsiasi modifica apportata alle foto di qualsiasi utente dell'app.

Nella Dashboard gestione app, accedi a Prodotti > Webhooks, seleziona Utente dal menu a discesa, quindi clicca su Attiva iscrizione a questo oggetto.
Scelta dell'oggetto User
Inserisci l'URL dell'endpoint nel campo URL di callback e inserisci una stringa nel campo Token di verifica. Questa stringa verrà inclusa in tutte le richieste di verifica. Se stai usando una delle nostre app di esempio, questa dovrebbe essere la stessa stringa utilizzata per la variabile di configurazione TOKEN dell'app.
Se desideri che i payload di notifica per l'evento includano i nomi dei campi modificati e i loro nuovi valori, imposta Includi valori su Sì.
Inserimento di un URL dell'endpoint e una stringa del token di verifica
Dopo aver cliccato su Verifica e salva, invieremo all'endpoint una richiesta di verifica, che dovrai convalidare. Se l'endpoint convalida correttamente la richiesta, dovresti vedere qualcosa di simile:
Convalida eseguita correttamente
L'ultimo passaggio consiste nell'attivare l'iscrizione per i singoli campi. Attiva l'iscrizione per il campo photos e invia una notifica per l'evento di prova.
Attivazione dell'iscrizione per il campo Photos sull'oggetto User
Se l'endpoint è stato configurato correttamente, dovrebbe convalidare il payload ed eseguire qualsiasi codice configurati in caso di convalida eseguita correttamente. Se stai utilizzando la nostra app di esempio, carica l'URL dell'app nel browser web. Dovrebbe visualizzare i contenuti del payload:
App di esempio che mostra il payload della notifica di prova

Passaggi successivi

Ora che conosci la modalità di configurazione dei webhook, ti consigliamo di fare riferimento ai nostri documenti aggiuntivi che descrivono i passaggi aggiuntivi necessari durante la configurazione di webhook per prodotti specifici: