Les Webhooks déclenchent des notifications en temps réel via des requêtes HTTP pour vous informer immédiatement des évènements liés à des champs spécifiques. Par exemple, vous pouvez recevoir une notification lorsqu’un·e utilisateur·ice de votre application rejoint un nouveau salon ou une nouvelle session, ou souscrit un abonnement. Ainsi, vous n’avez pas besoin d’émettre une requête pour connaître les modifications effectuées, et cela vous évite d’atteindre votre plafond⁠.

Configuration d’un serveur pour recevoir des notifications de Webhook

Pour recevoir des notifications de Webhook, votre serveur DOIT être en mesure d’accepter et de traiter des requêtes HTTPS et DOIT également disposer d’un certificat TLS/SSL valide. Les certificats auto-signés ne sont pas pris en charge.

Pour plus d’informations sur la façon de configurer un serveur pour recevoir des demandes de notification de Webhook, consultez Création d’un point de terminaison⁠ dans la documentation Facebook pour les développeurs et développeuses.

Configuration des Webhooks pour votre application dans le tableau de bord Meta Horizon

Pour configurer des Webhooks :

Dans le Tableau de bord développeur·se⁠, cliquez sur Development > Webhooks (Développement > Webhooks), puis sélectionnez votre application dans le menu déroulant.

Accessing Webhooks Configuration in the App Dashboard

Sur la page des Webhooks, cliquez sur Set Up Webhooks (Configurer Webhooks).

Saisissez l’URL du point de terminaison dans le champ Callback URL (URL de rappel). Pour Verify Token (Vérifier le token), indiquez une valeur que vous pouvez utiliser pour valider les demandes de vérification⁠ de Facebook.

Pour inclure dans les charges utiles de notification les noms des champs qui ont été modifiés ainsi que leurs nouvelles valeurs, activez Include Values (Inclure les valeurs).

Cliquez sur Créer. Facebook enverra ensuite à votre point de terminaison une demande de vérification que vous devrez valider⁠. Si votre point de terminaison a été correctement configuré, la boîte de dialogue Webhooks devrait apparaître comme dans l’image suivante.

Successful Creation of a Webhooks Subscription

Pour terminer, cliquez sur Subscribe (S’abonner) à côté des champs de Webhooks pour lesquels vous voulez recevoir une notification.

Si vous voulez qu’une notification de test soit envoyée à votre point de terminaison, vérifiez que votre Webhook est bien activé dans les paramètres, puis :

Cliquez sur Test pour le champ pour lequel vous souhaitez obtenir la notification de test.

Dans l’écran Field Sample (Échantillon de champ), cliquez sur Send to My Server (Envoyer à mon serveur).

Références des champs de Webhooks

Plusieurs évènements de champs de Webhooks peuvent être regroupés dans une seule et même demande de notification, mais cela n’est pas garanti. Veuillez gérer dans le champ changes indiqué ci-dessous les scénarios dans lesquels un seul ou plusieurs évènements de champs sont envoyés dans une seule et même demande de notification de Webhook.

Structure d’une demande de notification de Webhook de base

{
  "entry": [
    {
      "id": string,
      "time": number (Unix Timestamp),
      "changes": Array<WebhookFieldEvent>
    }
  ],
  "object": "application"
}

Champs multijoueurs

join_intent

L’évènement join_intent est envoyé à votre serveur lorsqu’une personne a accepté une invitation dans le jeu ou a rejoint une session de jeu multijoueur.

Servez-vous-en pour :

Prévenir les autres qu’un nouveau joueur ou une nouvelle joueuse rejoindra la destination

Réserver un emplacement dans le salon pour la personne entrante avec lobby_session_id et match_session_id

Gérer la logique supplémentaire côté serveur qui peut être effectuée en prévision de l’arrivée de la personne.

{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1718052945,
      "changes": [
        {
          "field": "join_intent",
          "value": {
            "destination_api_name": "destination_api_name",
            "joining_user": "10149999707612630",
            "lobby_session_id": "test_lobby_session_id",
            "match_session_id": "test_match_session_id"
          }
        }
      ]
    }
  ],
  "object": "application"
}

Valeurs

Nom	Type	Description
`destination_api_name`	`string`	Nom de l’API de la destination que la personne souhaite rejoindre.
`joining_user`	`string`	Identifiant de l’utilisateur ou utilisatrice qui rejoint la session.
`lobby_session_id`	`type`	ID de session du salon que l’utilisateur ou utilisatrice souhaite rejoindre.
`match_session_id`	`string`	ID de session du match que l’utilisateur ou utilisatrice souhaite rejoindre.

Champ de commande

order_status

L’évènement order_status est envoyé à votre serveur lorsqu’un utilisateur ou une utilisatrice a effectué un achat pour tout contenu complémentaire, ou si un achat complémentaire existant a été mis à jour (par exemple, consommation, remboursement, chargeback).

Servez-vous-en pour :

Suivre les nouveaux achats intégrés concernant votre application

Suivre les achats intégrés remboursés concernant votre application

{
  "entry": {
    "id": "345533925309564",
    "time": 1718052945,
    "changes": [
      {
        "field": "order_status",
        "value": {
          "event_time": "1659742639",
          "user_id": "10149999707612630",
          "product_info": {
            "notification_type": "PURCHASED",
            "reporting_id": "03f8833e-9c02-4fa0-978f-4cfe91f86bae",
            "sku": "item_sku_1",
            "developer_payload": "{\"quoteId\": 1234567}"
          }
        }
      }
    ]
  }
}

Valeurs

Nom	Type	Description
`event_time`	`Unix timestamp`	Heure à laquelle la commande a été passée.
`user_id`	`numeric string`	Propriétaire de l’ajout.
`product_info`	`dict`	Objet contenant les détails de la commande ou de l’article.
`product_info.notification_type`	`string`	Type d’évènement de commande. (ACHETÉ, REMBOURSÉ, CHARGEBACK)
`product_info.reporting_id`	`string`	UUID unique généré pour la commande à des fins de génération de rapports.
`product_info.sku`	`string`	SKU unique de l’achat intégré concernant cette commande.
`product_info.developer_payload`	`dict`	Chaîne non formatée contenant des informations sélectionnées par l’équipe de développement.

Champs d’abonnement

Pour vous abonner aux champs de Webhook d’abonnement, vous devez avoir effectué un contrôle de l’utilisation des données pour les abonnements et l’identifiant utilisateur·ice.

subscription_started

L’évènement subscription_started est envoyé à votre serveur lorsqu’une personne entame un abonnement à votre application. Cela pourrait être soit pour un nouvel abonnement, soit pour un nouvel abonnement qui a expiré puis repris.

{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1715797294,
      "changes": [
        {
          "field": "subscription_started",
          "value": {
            "owner_id": "1234567890",
            "source_app": "TWILIGHT",
            "subscription": {
              "id": "1234567890",
              "trial_type": "TRIAL_OFFER",
              "sku": "bronzeTier0",
              "period_start_time": "1711956272",
              "period_end_time": "1711956272",
              "next_renewal_time": "1711956272",
              "is_active": true,
              "is_trial": false,
              "current_price_term": {
                "term": "MONTHLY",
                "price": "19.99",
                "currency": "USD"
              },
              "next_price_term": {
                "term": "MONTHLY",
                "price": "1999.00",
                "currency": "USD"
              }
            }
          }
        }
      ]
    }
  ],
  "object": "application"
}

subscription_renewal_success

L’évènement subscription_renewal_success est envoyé à votre serveur dès que le renouvellement d’un abonnement existant à votre application aboutit. Étant donné que les abonnements sont régulièrement renouvelés et que le nombre de renouvellements correspond au nombre d’abonnements actifs, il est important de vous assurer que le serveur peut traiter des volumes potentiellement élevés de demandes d’évènements de Webhook subscription_renewal_success simultanées dans la mesure où vous décidez de vous abonner à ce champ de Webhook. Pour gérer efficacement ce type de trafic, vérifiez que votre serveur est en mesure de traiter une telle charge de travail si votre application comporte un grand nombre d’abonnements.

{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1715796778,
      "changes": [
        {
          "field": "subscription_renewal_success",
          "value": {
            "owner_id": "1234567890",
            "subscription": {
              "id": "1234567890",
              "sku": "bronzeTier0",
              "period_start_time": "1711956272",
              "period_end_time": "1711956272",
              "next_renewal_time": "1711956272",
              "is_active": true,
              "is_trial": false,
              "current_offer": {
                "term": "MONTHLY",
                "price": "19.99",
                "currency": "USD"
              },
              "next_offer": {
                "term": "MONTHLY",
                "price": "19.99",
                "currency": "USD"
              }
            }
          }
        }
      ]
    }
  ],
  "object": "application"
}

subscription_canceled

L’évènement subscription_canceled est envoyé à votre serveur lorsqu’une personne résilie son abonnement à votre application.

{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1717714215,
      "changes": [
        {
          "value": {
            "owner_id": "7663588487057119",
            "subscription": {
              "id": "228e599134540916c63a33cd6aa485379deb3a959ba4075f323b31bb1dda7ecc",
              "sku": "bronze_test_01",
              "period_start_time": "1717714180",
              "period_end_time": "1720306180",
              "next_renewal_time": "1720306180",
              "is_active": true,
              "is_trial": false,
              "current_price_term": {
                "term": "MONTHLY",
                "price": "1.99",
                "currency": "USD"
              },
              "next_price_term": {
                "term": "MONTHLY",
                "price": "1.99",
                "currency": "USD"
              }
            },
            "cancel_reason": "PRICE_TOO_EXPENSIVE"
          },
          "field": "subscription_canceled"
        }
      ]
    }
  ],
  "object": "application"
}

subscription_uncanceled

L’évènement subscription_uncanceled est envoyé à votre serveur lorsqu’une personne annule sa demande de résiliation d’abonnement à votre application avant son expiration.

{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1717714175,
      "changes": [
        {
          "value": {
            "owner_id": "7663588487057119",
            "subscription": {
              "id": "228e599134540916c63a33cd6aa485379deb3a959ba4075f323b31bb1dda7ecc",
              "sku": "bronze_test_01",
              "period_start_time": "1717713920",
              "period_end_time": "1720305920",
              "next_renewal_time": "1720305920",
              "is_active": true,
              "is_trial": false,
              "current_price_term": {
                "term": "MONTHLY",
                "price": "1.99",
                "currency": "USD"
              },
              "next_price_term": {
                "term": "MONTHLY",
                "price": "1.99",
                "currency": "USD"
              }
            }
          },
          "field": "subscription_uncanceled"
        }
      ]
    }
  ],
  "object": "application"
}

subscription_expired

L’évènement subscription_expired est envoyé à votre serveur lorsqu’un abonnement à votre application expire. Étant donné que les abonnements expirent régulièrement et que le nombre d’expirations correspond au nombre d’abonnements résiliés, il est important de vous assurer que le serveur peut traiter des volumes potentiellement élevés de demandes d’évènements de Webhook subscription_expired simultanées dans la mesure où vous décidez de vous abonner à ce Webhook. Pour gérer efficacement ce type de trafic, vérifiez que votre serveur est en mesure de traiter une telle charge de travail si votre application comporte un grand nombre d’abonnements.

{
  "entry": [
    {
      "id": "345533925309564",
      "time": 1717714227,
      "changes": [
        {
          "value": {
            "owner_id": "7663588487057119",
            "subscription": {
              "id": "228e599134540916c63a33cd6aa485379deb3a959ba4075f323b31bb1dda7ecc",
              "sku": "bronze_test_01",
              "period_start_time": "1717714180",
              "period_end_time": "1717714221",
              "next_renewal_time": "1717714221",
              "is_active": false,
              "is_trial": false,
              "current_price_term": {
                "term": "MONTHLY",
                "price": "1.99",
                "currency": "USD"
              },
              "next_price_term": {
                "term": "MONTHLY",
                "price": "1.99",
                "currency": "USD"
              }
            }
          },
          "field": "subscription_expired"
        }
      ]
    }
  ],
  "object": "application"
}

Valeurs

Nom	Type	Description
`owner_id`	`string`	ID utilisateur·ice limité à l’application de la personne à laquelle cet abonnement appartient.
`source_app`	`string`	Application Meta à partir de laquelle un abonnement a été entamé pour l’évènement `subscription_started`.
`subscription`	`subscription`	Données d’abonnement liées à l’évènement.
`cancel_reason`	`string`	Raison pour laquelle l’abonnement a été résilié pour l’évènement `subscription_canceled`.

Abonnement

Nom	Type	Description
`id`	`string`	Identifiant unique d’un abonnement qui sera cohérent pour tous les évènements de champ d’abonnement. Il peut être utilisé pour associer tous les évènements d’abonnement à cet ID.
`trial_type`	`?string`	Défini sur INTRO_OFFER ou TRIAL_OFFER si l’abonnement bénéficie actuellement d’un tarif de lancement ou d’une période d’essai. Ne sera pas défini s’il s’agit d’un abonnement payant normal.
`sku`	`string`	Données d’abonnement liées à l’évènement.
`period_end_time`	`string`	Horodatage Unix mentionnant la date à laquelle la période d’abonnement actuelle prendra fin.
`period_start_time`	`string`	Horodatage Unix mentionnant la date à laquelle l’abonnement actuel a commencé.
`next_renewal_time`	`string`	Horodatage Unix mentionnant la date à laquelle l’abonnement sera renouvelé.
`current_price_term`	`price_term`	Tarif et durée de l’abonnement actuel.
`next_price_term`	`price_term`	Tarif et durée du prochain renouvellement d’abonnement.
`is_active`	`bool`	Défini sur Vrai lorsqu’un abonnement est actif.
`is_trial`	`bool`	Défini sur Vrai lorsque la période d’abonnement la plus récente est une période d’essai (7 jours, 14 jours, 30 jours). N’indique pas que l’abonnement à proprement parler est actif.

Modalités tarifaires

Nom	Type	Description
`term`	`string?`	Fréquence de l’abonnement (par exemple : MENSUEL, ANNUEL, HEBDOMADAIRE, etc.). Peut être vide pour les abonnements d’essai.
`currency`	`string`	Devise du tarif. Par exemple : USD, EUR
`price`	`string`	Prix de l’abonnement sans le symbole de devise.