Webhooks

Présentation

Les webhooks permettent d’abonner les applications d’intégration personnalisée à des évènements dans Workplace et de recevoir des mises à jour en temps réel. Quand une modification est apportée dans Workplace, une requête HTTPS POST est envoyée à une URL de rappel pour chaque application d’intégration personnalisée abonnée au sujet de webhook pertinent.

Les applications sont ainsi plus efficaces, car elles savent exactement quand une modification a été apportée et ne dépendent plus des requêtes continues ou même périodiques de l’API Graph pour obtenir les contenus les plus récents.

La prise en charge des webhooks pour Workplace est assurée par le même framework que les webhooks pour l’API Graph.

Abonnement aux sujets de webhook

La boîte de dialogue Modifier l’intégration personnalisée contient un onglet par sujet de webhook disponible pour les applications dans Workplace.

Section Webhooks dans la boîte de dialogue Modifier l’intégration personnalisée

Pour ajouter un nouvel abonnement webhook à un sujet donné, fournissez une URL de rappel et un token de vérification, puis sélectionnez les champs d’abonnement dont vous avez besoin pour les fonctionnalités que proposera votre application.

Gestion des requêtes de vérification

Quand vous ajoutez un nouvel abonnement ou modifiez un abonnement existant, les serveurs de Meta envoient une requête GET à votre URL de rappel afin de vérifier la validité du serveur de rappel.

Une chaîne de requête est ajoutée à cette URL avec les paramètres suivants :

• hub.mode : la chaîne subscribe est transmise dans ce paramètre
• hub.challenge : une chaîne aléatoire
• hub.verify_token : la valeur du verify_token spécifiée lors de la création de l’abonnement

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

• vérifier que la valeur hub.verify_token correspond à la chaîne définie dans le champ Vérifier le token lorsque vous configurez le webhook ;
• répondre avec la valeur hub.challenge.

Sécurité des webhooks

Tous les appels webhook aux URL de rappel définies par l’équipe de développement sont réalisés via HTTPS pour garantir la sécurité des charges utiles des webhooks pendant le transport.

Pour renforcer la sécurité, une X-Hub-Signature-256 avec un en-tête HTTP est intégrée dans chaque charge utile POST, que nous vous recommandons d’utiliser pour vérifier que la charge utile provient d’un serveur de Meta.

Pour tout savoir sur ce processus, consultez la documentation sur le framework des webhooks.

Tous les appels webhook aux URL de rappel définies par l’équipe de développement sont réalisés via HTTPS pour garantir la sécurité des charges utiles des webhooks pendant le transport.

Abonnement aux webhooks via un appel d’API

Les appels d’API servant à lire ou à modifier les abonnements webhook doivent être réalisés avec un token d’application plutôt qu’avec le token d’intégration personnalisée habituel. Pour générer un token d’application, concaténez l’ID de l’app, le symbole « | » et la clé secrète.

Par exemple :

Obtenir les abonnements actuels aux webhooks (avec le token de l’application)

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

Ajouter un nouvel abonnement webhook (avec le token de l’application)

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}

Résolution des problèmes liés aux abonnements des Pages/applications

Si vous ne recevez pas les webhooks comme prévu, vérifiez la configuration de l’abonnement entre la page et l’application. Celle-ci est effectuée automatiquement, mais des erreurs peuvent se produire. Par exemple, si la diffusion d’un webhook ne fonctionne pas sur une période prolongée, cet abonnement peut être supprimé. Dans le cas d’applications tierces, une alerte est alors affichée dans le tableau de bord des applications.

Pour vérifier cet abonnement, vous pouvez utiliser les appels d’API suivants :

Obtenir l’abonnement application/page actuel (avec le token de la page)

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

Pour recréer cet abonnement, vous pouvez utiliser les appels d’API suivants :

Recréer l’abonnement app/page actuel (avec le token de la page)

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

Sujets de webhooks

Les activités réalisées dans Workplace sont regroupées en sujets. Chaque sujet contient un certain nombre de champs associés à des évènements sur un sujet donné. Les applications peuvent être abonnées aux notifications webhook de chaque sujet ou à certains champs de chaque sujet.

Les webhooks sont actuellement disponibles pour les sujets et groupes suivants dans Workplace :

Page

Pour en savoir plus, consultez les documents de référence sur le sujet Page.

Groupes

Pour en savoir plus, consultez les documents de référence sur le sujet Groupe.

Utilisateur·ice

Pour en savoir plus, consultez les documents de référence sur le sujet Utilisateur.

Sécurité

Pour en savoir plus, consultez les documents de référence sur le sujet Sécurité.

admin_activity

Évènements déclenchés quand un admin rejoint ou quitte une communauté Workplace.

compromised_credentials

Évènements déclenchés quand nous soupçonnons que les mots de passe de certains comptes utilisateur d’une communauté Workplace ont été exposés.

files

Évènements déclenchés quand une activité est détectée dans les fichiers Workplace.

groups

Évènements déclenchés quand une personne crée ou rejoint un groupe inter-entreprise Workplace.

integrations

Évènements déclenchés quand un admin crée ou modifie les propriétés d’intégration.

invites

Évènements déclenchés quand une personne rejoint Workplace via une auto-invitation.

passwords

Évènements déclenchés quand une personne modifie son mot de passe ou demande à le réinitialiser.

sessions

Évènements déclenchés quand une personne se connecte ou se déconnecte de Workplace.

two_factor

Évènements déclenchés quand une personne active ou désactive l’authentification à deux facteurs.

reseller_events

Évènements relatifs au revendeur.

Liens

Pour en savoir plus, consultez les documents de référence sur le sujet Liens.

Bibliothèque de connaissances

Pour en savoir plus, consultez les documents sur l’élément Catégorie de la bibliothèque de connaissances de l’API Graph.