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.

Création d’un point de terminaison

Votre point de terminaison doit être capable de traiter deux types de demandes HTTPS : Demandes de vérification et Notifications d’évènement. Comme les deux demandes utilisent le protocole HTTPS, votre serveur doit disposer d’un certificat TLS ou SSL valide, correctement configuré et installé. Les certificats auto-signés ne sont pas pris en charge.

Les sections ci-dessous expliquent le contenu de chaque type de demande et comment y répondre. Vous pouvez également utiliser notre exemple d’application déjà configuré pour traiter ces demandes.

Demandes de vérification

À chaque fois que vous configurerez le produit Webhooks dans votre Espace App, nous enverrons une demande GET à l’URL de votre point de terminaison. Les demandes de vérification comprennent les paramètres de chaîne de requêtes suivants, ajoutés à la fin de votre URL de point de terminaison. Ils ressembleront à ceci :

Exemple de demande de vérification

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

Paramètre	Exemple de valeur	Description
`hub.mode`	`subscribe`	Cette valeur sera toujours définie sur `subscribe`.
`hub.challenge`	`1158201444`	Vous devez nous transmettre un `int`.
`hub.verify_token`	`meatyhamhock`	Une chaîne que nous récupérons à partir du champ Vérifier le token dans l’Espace App de votre application. Vous configurez cette chaîne lorsque vous terminez les étapes Paramètres de configuration Webhooks.

Remarque :PHP convertit les points (.) en tirets bas (_) dans le nom des paramètres.

Validation des demandes de vérification

Chaque fois que votre point de terminaison reçoit une demande de vérification, il doit :

vérifier que la valeur hub.verify_token correspond à la chaîne que vous avez définie dans le champ Vérifier le token lorsque vous configurez le produit Webhooks dans votre Espace App (vous n’avez pas encore configuré cette chaîne de tokens) ;
répondre avec la valeur hub.challenge.

Si vous êtes sur votre espace app et que vous configurez votre produit Webhooks (et, par conséquent, déclenchez une demande de vérification), le tableau de bord indiquera si votre point de terminaison a validé la demande correctement. Si vous utilisez le point de terminaison /app/inscriptions de l’API Graph pour configurer le produit Webhooks, l’API indiquera la réussite ou l’échec avec une réponse.

Notifications d’évènement

Lorsque vous configurez votre produit Webhooks, vous vous abonnez à des fields spécifiques d’un type object (par exemple, le champ photos de l’objet user). À chaque modification de l’un de ces champs, nous enverrons à votre point de terminaison une demande POST avec une charge utile JSON décrivant la modification.

Par exemple, si vous vous abonnez au champ photos de l’objet user et que l’un·e des utilisateurs ou utilisatrices de votre application a publié une photo, nous vous enverrons une demande POST qui ressemblerait à ceci :

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

Contenu de la charge utile

Les charges utiles contiendront un objet décrivant la modification. Lorsque vous configurez le produit Webhooks, vous pouvez indiquer si les charges utiles doivent uniquement contenir le nom des champs modifiés ou inclure aussi les nouvelles valeurs.

Nous formatons toutes les charges utiles avec JSON, afin que vous puissiez analyser la charge utile en utilisant des méthodes ou des packages d’analyse JSON courants.

Nous ne stockons aucune donnée de notification d’évènement Webhook que nous vous envoyons, alors assurez-vous de saisir et de stocker tout contenu de charge utile que vous souhaitez conserver.

La plupart des charges utiles contiendront les propriétés communes suivantes, mais le contenu et la structure de chaque charge utile varient en fonction des champs d’objet auxquels vous vous êtes inscrit. Reportez-vous au document de référence de chaque objet pour savoir quels champs seront inclus.

Propriété	Description	Type
`object`	Le type de l’objet (par exemple, `user`, `page`, etc.)	`string`
`entry`	Un tableau contenant un objet décrivant les modifications. Les modifications multiples de différents objets du même type peuvent être regroupées.	`array`
`id`	L’ID de l’objet	`string`
`changed_fields`	Un tableau de chaînes indiquant les noms des champs modifiés. Uniquement inclus si vous désactivez le paramètre Inclure les valeurs lors de la configuration du produit Webhooks dans l’Espace App de votre application.	`array`
`changes`	Un tableau contenant un objet décrivant les champs modifiés et leurs nouvelles valeurs. Uniquement inclus si vous activez le paramètre Inclure les valeurs lors de la configuration du produit Webhooks dans l’Espace App de votre application.	`array`
`time`	Un horodatage UNIX indiquant le moment de l’envoi de la notification d’évènement (et non le moment auquel la modification déclenchant la notification s’est produite).	`int`

Validation des charges utiles

Nous signons toutes les charges utiles de notification d’évènement avec une signature SHA256 et incluons la signature dans l’en-tête X-Hub-Signature de la demande, précédée de sha1=. La validation de la charge utile n’est pas obligatoire, elle est cependant conseillée.

Pour valider la charge utile :

Générez une signature SHA256 utilisant la charge utile et la clé secrète de votre application.
Comparez votre signature à la signature dans l’en-tête X-Hub-Signature-256 (après sha256=). Si les signatures correspondent, la charge utile est authentique.

Réponse à des notifications d’évènement

Votre point de terminaison devrait répondre à toutes les notifications d’évènement avec 200 OK HTTPS.

Fréquence

Les notifications d’évènement sont agrégées, puis envoyées dans un lot pouvant contenir jusqu’à 1 000 mises à jour. Toutefois, nous ne pouvons pas garantir le traitement par lot. Aussi, veillez à configurer vos serveurs de sorte qu’ils puissent traiter chaque Webhook individuellement.

Si une mise à jour envoyée à votre serveur échoue, nous vous la renverrons immédiatement, puis la renverrons plusieurs autres fois, avec une fréquence d’envoi de plus en plus faible, durant les 36 heures suivantes. Dans de tels cas de figure, votre serveur devrait être capable de gérer la déduplication. Les réponses non reconnues seront supprimées après 36 heures.

Remarque : la fréquence d’envoi des notifications d’évènement avec Messenger est différente. Pour plus d’informations, reportez-vous à la documentation sur les webhooks de la plateforme Messenger.

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.

É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 :