Démarrer

Ce document explique comment configurer un webhook qui vous avertira, chaque fois que les utilisateurs et utilisatrices de votre application publient des modifications sur leurs photos. Une fois que vous aurez compris comment configurer ce Webhook, vous saurez comment configurer tous les Webhooks.

Configurer un Webhook nécessite de :

créer un point de terminaison sur un serveur sécurisé capable de traiter les demandes HTTPS ;
configurer le produit Webhooks dans l’Espace App de votre application.

Ces étapes sont expliquées en détail ci-après.

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.

Configuration du produit Webhooks

Lorsque votre point de terminaison ou votre exemple d’application est prêt, utilisez l’Espace App de votre application pour ajouter et configurer le produit Webhooks. Vous pouvez aussi le faire dans le cadre d’un programme en utilisant le point de terminaison /{app-id}/subscriptions pour tous les Webhooks à l’exception d’Instagram.

Dans cet exemple, nous utiliserons le tableau de bord pour configurer un Webhook qui s’inscrit à toutes les modifications apportées aux photos de toutes les personnes utilisant votre application.

Dans l’Espace App, accédez à Produits > Webhooks, sélectionnez Utilisateur dans le menu déroulant, puis cliquez sur S’abonner à cet objet.
Choisir l’objet Utilisateur.
Saisissez l’URL de votre point de terminaison dans le champ URL de rappel et entrez une chaîne dans le champ Vérifier le token. Nous inclurons cette chaîne dans toutes les demandes de vérification. Si vous utilisez l’un de nos exemples d’application, il doit s’agir de la même chaîne que vous avez utilisée pour la variable de configuration TOKEN de votre application.
Si vous souhaitez que les charges utiles des notifications d’évènement incluent le nom des champs qui ont changé ainsi que leurs nouvelles valeurs, définissez l’option Inclure les valeurs sur Oui.
Saisie d’une URL de point de terminaison et d’une chaîne de token de vérification
Lorsque vous aurez cliqué sur Vérifier et enregistrer, nous enverrons à votre point de terminaison une demande de vérification que vous devrez valider. Si votre point de terminaison valide avec succès la demande, vous devriez voir ceci :
Validation réussie.
La dernière étape consiste à vous abonner à des champs individuels. Abonnez-vous au champ photos et envoyez une notification d’évènement de test.
S’abonner au champ Photos sur l’objet Utilisateur.
Si votre point de terminaison est configuré correctement, il devrait valider la charge utile et exécuter le code que vous avez défini lors de la validation. Si vous utilisez notre exemple d’application, chargez l’URL de l’application dans votre navigateur Web. Il devrait afficher le contenu de la charge utile :
Exemple d’application affichant la charge utile de notification de test.

mTLS pour Webhooks

Mutual TLS (mTLS) est une méthode d’authentification mutuelle.

mTLS garantit que les parties à chaque extrémité d’une connexion réseau sont bien celles qu’elles prétendent être en vérifiant qu’elles disposent toutes deux de la bonne clé privée. Les informations contenues dans leurs certificats TLS respectifs constituent une vérification supplémentaire.

Comment configurer mTLS

Après l’activation du protocole mTLS pour votre abonnement au compte WhatsApp Business, Meta fournira un certificat client accompagné de son certificat intermédiaire de signature. Ces deux certificats servent à établir une négociation TLS pour les requêtes Webhook vers votre serveur. Votre serveur pourra alors vérifier l’identité de l’expéditeur·ice de ces requêtes via la chaîne de confiance et le nom usuel (CN).

Le certificat client est signé par un certificat CA intermédiaire, DigiCert SHA2 High Assurance Server CA, puis par un certificat CA racine, DigiCert High Assurance EV Root CA. Notez que le certificat intermédiaire signe aussi le certificat pour graph.facebook.com :

Vérification du certificat client

Après avoir configuré HTTPS pour la réception des requêtes Webhook, effectuez les étapes suivantes pour vérifier le certificat client et son nom usuel client.webhooks.fbclientcerts.com :

Installez le certificat racine
Vérifiez le certificat client par rapport au certificat racine
Vérifiez le nom usuel (client.webhooks.fbclientcerts.com) du certificat client

Remarque : les serveurs recevant des Webhooks doivent utiliser HTTPS. Par ailleurs, nous vérifions toujours le certificat de votre serveur HTTPS pour des raisons de sécurité.

Exemple

Selon la configuration de votre serveur, certains détails des étapes ci-dessus peuvent varier. Nous illustrons cela par deux exemples, l’un pour Nginx et l’autre pour AWS Application Load Balancer (ALB).

Nginx

Téléchargez le certificat racine (DigiCert High Assurance EV Root CA) de DigiCert sur votre serveur, par exemple /etc/ssl/certs/DigiCert_High_Assurance_EV_Root_CA.pem

Activez mTLS via les directives Nginx (exemple de capture d’écran)

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

Vérifiez que le nom usuel de la variable intégrée de Nginx $ssl_client_s_dn est égal à "client.webhooks.fbclientcerts.com" (exemple de capture d’écran)
```
if ($ssl_client_s_dn ~ "CN=client.webhooks.fbclientcerts.com") {
    return 200 "$ssl_client_s_dn";
}
```

AWS Application Load Balancer (ALB)

Téléchargez le certificat intermédiaire (DigiCert SHA2 High Assurance Server CA) de DigiCert dans un compartiment S3. Le certificat racine n’est pas accepté par AWS parce qu’il est signé avec l’algorithme SHA1withRSA, alors que le certificat intermédiaire est signé avec SHA256withRSA et donc accepté.
Configurez l’auditeur HTTPS sur ALB pour activer mTLS avec le trust store contenant le certificat dans le compartiment S3 (exemple de capture d’écran).
Dans votre code d’application, extrayez le nom usuel de l’en-tête HTTP “X-Amzn-Mtls-Clientcert-Subject”, puis vérifiez qu’il est égal à “client.webhooks.fbclientcerts.com”.

Étapes suivantes

Maintenant que vous savez comment configurer des Webhooks, vous pouvez consulter nos documents complémentaires, qui décrivent les étapes supplémentaires impliquées lors de la configuration de Webhooks pour des produits spécifiques :