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.

Create an Endpoint

Your endpoint must be able to process two types of HTTPS requests: Verification Requests and Event Notifications. Since both requests use HTTPs, your server must have a valid TLS or SSL certificate correctly configured and installed. Self-signed certificates are not supported.

The sections below explain what will be in each type of request and how to respond to them. Alternatively, you can use our sample app which is already configured to process these requests.

Verification Requests

Anytime you configure the Webhooks product in your App Dashboard, we'll send a GET request to your endpoint URL. Verification requests include the following query string parameters, appended to the end of your endpoint URL. They will look something like this:

Sample Verification Request

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

Parameter	Sample Value	Description
`hub.mode`	`subscribe`	This value will always be set to `subscribe`.
`hub.challenge`	`1158201444`	An `int` you must pass back to us.
`hub.verify_token`	`meatyhamhock`	A string that that we grab from the Verify Token field in your app's App Dashboard. You will set this string when you complete the Webhooks configuration settings steps.

Note: PHP converts periods (.) to underscores (_) in parameter names.

Validating Verification Requests

Whenever your endpoint receives a verification request, it must:

Verify that the hub.verify_token value matches the string you set in the Verify Token field when you configure the Webhooks product in your App Dashboard (you haven't set up this token string yet).
Respond with the hub.challenge value.

If you are in your App Dashboard and configuring your Webhooks product (and thus, triggering a Verification Request), the dashboard will indicate if your endpoint validated the request correctly. If you are using the Graph API's /app/subscriptions endpoint to configure the Webhooks product, the API will indicate success or failure with a response.

Event Notifications

When you configure your Webhooks product, you will subscribe to specific fields on an object type (e.g., the photos field on the user object). Whenever there's a change to one of these fields, we will send your endpoint a POST request with a JSON payload describing the change.

For example, if you subscribed to the user object's photos field and one of your app's Users posted a Photo, we would send you a POST request that would look something like this:

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"
}

Payload Contents

Payloads will contain an object describing the change. When you configure the webhooks product, you can indicate if payloads should only contain the names of changed fields, or if payloads should include the new values as well.

We format all payloads with JSON, so you can parse the payload using common JSON parsing methods or packages.

We do not store any Webhook event notification data that we send you, so be sure to capture and store any payload content that you want to keep.

Most payloads will contain the following common properties, but the contents and structure of each payload varies depending on the object fields you are subscribed to. Refer to each object's reference document to see which fields will be included.

Property	Description	Type
`object`	The object's type (e.g., `user`, `page`, etc.)	`string`
`entry`	An array containing an object describing the changes. Multiple changes from different objects that are of the same type may be batched together.	`array`
`id`	The object's ID	`string`
`changed_fields`	An array of strings indicating the names of the fields that have been changed. Only included if you disable the Include Values setting when configuring the Webhooks product in your app's App Dashboard.	`array`
`changes`	An array containing an object describing the changed fields and their new values. Only included if you enable the Include Values setting when configuring the Webhooks product in your app's App Dashboard.	`array`
`time`	A UNIX timestamp indicating when the Event Notification was sent (not when the change that triggered the notification occurred).	`int`

Validating Payloads

We sign all Event Notification payloads with a SHA256 signature and include the signature in the request's X-Hub-Signature-256 header, preceded with sha256=. You don't have to validate the payload, but you should.

To validate the payload:

Generate a SHA256 signature using the payload and your app's App Secret.
Compare your signature to the signature in the X-Hub-Signature-256 header (everything after sha256=). If the signatures match, the payload is genuine.

Responding to Event Notifications

Your endpoint should respond to all Event Notifications with 200 OK HTTPS.

Frequency

Event Notifications are aggregated and sent in a batch with a maximum of 1000 updates. However batching cannot be guaranteed so be sure to adjust your servers to handle each Webhook individually.

If any update sent to your server fails, we will retry immediately, then try a few more times with decreasing frequency over the next 36 hours. Your server should handle deduplication in these cases. Unacknowledged responses will be dropped after 36 hours.

Note: The frequency with which Messenger event notifications are sent is different. Please refer to the Messenger Platform Webhooks documentation for more information.

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 per ricevere gli aggiornamenti relativi a 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 Ricevi gli aggiornamenti di 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 configurato 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.

mTLS per webhook

Mutual TLS (mTLS) è un metodo per l'autenticazione reciproca.

mTLS garantisce che le parti alle due estremità di una connessione di rete siano chi dichiarano di essere verificando che entrambe abbiano la chiave privata corretta. Le informazioni contenute nei rispettivi certificati TLS consentono di eseguire ulteriori verifiche.

Come configurare mTLS

Dopo aver abilitato mTLS sul tuo abbonamento all'account WhatsApp Business, Meta presenterà un certificato client insieme al certificato intermedio di firma. Entrambi i certificati vengono usati per creare un handshake TLS di richieste webhook al tuo server. Il tuo server può quindi verificare l'identità del mittente di queste richieste tramite la catena di fiducia e il nome comune (CN).

Il certificato client è firmato da un certificato CA intermedio, DigiCert SHA2 High Assurance Server CA, e poi da un certificato CA root, DigiCert High Assurance EV Root CA. Il certificato intermedio firma anche il certificato per graph.facebook.com:

Verifica del certificato client

Dopo aver configurato HTTPS per ricevere le richieste webhook, completa i seguenti passaggi per verificare il certificato client e il suo nome comune client.webhooks.fbclientcerts.com:

Installa il certificato root.
Verifica il certificato client rispetto al certificato root.
Verifica il nome comune (client.webhooks.fbclientcerts.com) del certificato client.

Nota: i server che ricevono webhook devono usare HTTPS e noi verifichiamo sempre il certificato del server HTTPS per sicurezza.

Esempio

A seconda della configurazione del server, alcuni dettagli dei passaggi precedenti potrebbero variare. Illustriamo proponendo due esempi, uno per Nginx e uno per AWS Application Load Balancer (ALB).

Nginx

Scarica il certificato root (DigiCert High Assurance EV Root CA) da DigiCert sul tuo server, ad esempio /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem.

Abilita mTLS secondo le direttive Nginx (screenshot di esempio)

ssl_verify_client       on;
ssl_client_certificate  /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem;
ssl_verify_depth        3;

Verifica che il CN dalla variabile incorporata Nginx $ssl_client_s_dn sia uguale a "client.webhooks.fbclientcerts.com" (screenshot di esempio).
```
if ($ssl_client_s_dn ~ "CN=client.webhooks.fbclientcerts.com") {
    return 200 "$ssl_client_s_dn";
}
```

AWS Application Load Balancer (ALB)

Scarica il certificato intermedio (DigiCert SHA2 High Assurance Server CA) da DigiCert su un bucket S3. Il certificato root non è accettato da AWS perché firmato utilizzando l'algoritmo SHA1withRSA; il certificato intermedio è firmato utilizzando SHA256withRSA ed è quindi accettato.
Configura il listener HTTPS sull'ALB per abilitare mTLS con il trust store contenente il certificato nel bucket S3 (screenshot di esempio).
Nel codice dell'app, estrai il CN dall'intestazione HTTP "X-Amzn-Mtls-Clientcert-Subject" e verifica che sia uguale a “client.webhooks.fbclientcerts.com”.

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: