L’intégration webhook d’Adapty comprend les étapes suivantes :

1. Vous configurez votre endpoint :
   1. Assurez-vous que votre serveur peut traiter les requêtes Adapty avec l’en-tête Content-Type défini sur application/json.
   2. Configurez votre serveur pour recevoir la requête de vérification d’Adapty et répondre avec n’importe quel statut 2xx et un corps JSON.
   3. Gérez les événements d’abonnement une fois la connexion vérifiée.
2. Vous configurez et activez l’intégration webhook dans l’Adapty Dashboard. Vous pouvez également associer des événements Adapty à des noms d’événements personnalisés. Nous recommandons de tester dans l’environnement Sandbox avant de passer en production.
3. Adapty envoie une requête de vérification à votre serveur.
4. Votre serveur répond avec un statut 2XX et un corps JSON.
5. Dès qu’Adapty reçoit une réponse valide, il commence à envoyer les événements d’abonnement.

Configurez votre serveur pour traiter les requêtes Adapty

Adapty enverra à votre endpoint webhook 2 types de requêtes :

1. Requête de vérification : la requête initiale pour vérifier que la connexion est correctement configurée. Cette requête ne contiendra aucun événement et sera envoyée dès que vous cliquerez sur le bouton Save dans l’intégration Webhook de l’Adapty Dashboard. Pour confirmer que votre endpoint a bien reçu la requête de vérification, il doit répondre avec la réponse de vérification.
2. Événement d’abonnement : une requête standard que le serveur Adapty envoie chaque fois qu’un événement est créé. Votre serveur n’a pas besoin de répondre avec une réponse spécifique. La seule chose dont le serveur Adapty a besoin est de recevoir une réponse HTTP standard avec le code 200 s’il reçoit le message avec succès.

Demande de vérification

Après avoir activé l’intégration webhook dans l’Adapty Dashboard, Adapty enverra une requête POST de vérification contenant un objet JSON vide {} comme corps.

Configurez votre endpoint pour que le Content-Type header soit application/json, c’est-à-dire que votre endpoint serveur doit s’attendre à recevoir des requêtes webhook dont le payload est formaté en JSON.

Votre serveur doit répondre avec un code de statut 2xx et renvoyer n’importe quelle réponse JSON valide, par exemple :

{}

Une fois qu’Adapty reçoit la réponse de vérification au format correct avec un code de statut 2xx, votre intégration webhook Adapty est entièrement configurée.

Événements d’abonnement

Les événements d’abonnement sont envoyés avec l’en-tête Content-Type défini sur application/json et contiennent les données de l’événement au format JSON. Pour les types d’événements possibles et les structures de requête, consultez Types et champs des événements webhook.

Configurer l’intégration webhook dans l’Adapty Dashboard

Dans Adapty, vous pouvez configurer des flows distincts pour les événements de production et les événements de test reçus depuis l’environnement sandbox d’Apple ou Stripe, ou depuis un compte de test Google.

Pour les événements de production, utilisez le champ Production endpoint URL en indiquant l’URL à laquelle les callbacks seront envoyés. Configurez également le champ Authorization header value for production endpoint — l’en-tête permettant à votre serveur d’authentifier les événements Adapty. Notez que nous utiliserons la valeur renseignée dans le champ Authorization header value for production endpoint comme en-tête Authorization exactement telle quelle, sans aucune modification ni ajout.

Pour les événements de test, utilisez respectivement les champs Sandbox endpoint URL et Authorization header value for sandbox endpoint.

Pour configurer l’intégration webhook :

1. Ouvrez Integrations -> Webhook dans votre Adapty Dashboard.

2. Activez le bouton pour lancer l’intégration.
3. Remplissez les champs de l’intégration :

Champ	Description
Production endpoint URL	L’URL qu’Adapty utilise pour envoyer des requêtes HTTP POST pour les événements en production.
Authorization header value for production endpoint	L’en-tête que votre serveur utilisera pour authentifier les requêtes provenant d’Adapty en production. Notez que nous utiliserons la valeur spécifiée dans ce champ comme en-tête Authorization exactement telle que fournie, sans aucune modification ni ajout. Bien que non obligatoire, cette configuration est fortement recommandée pour renforcer la sécurité.

De plus, pour vos besoins de test dans l’environnement sandbox, deux autres champs sont disponibles :

Champ de test	Description
Sandbox endpoint URL	L’URL qu’Adapty utilise pour envoyer des requêtes HTTP POST pour les événements dans l’environnement sandbox.
Authorization header value for sandbox endpoint	L’en-tête que votre serveur utilisera pour authentifier les requêtes d’Adapty lors des tests dans l’environnement sandbox. Notez que nous utiliserons la valeur spécifiée dans ce champ comme en-tête Authorization exactement telle quelle, sans aucune modification ni ajout. Bien que non obligatoire, cette mesure est fortement recommandée pour renforcer la sécurité.

4. (optionnel) Choisissez les événements que vous souhaitez recevoir et associez leurs noms. Consultez nos Flux d’événements pour voir quels événements sont déclenchés dans différentes situations.

   Si vos identifiants d’événements diffèrent de ceux utilisés dans Adapty, conservez les identifiants de votre système tels quels et remplacez les identifiants d’événements Adapty par défaut par les vôtres dans la section Events names de la page Integrations -> Webhooks.

L’ID d’événement peut être n’importe quelle chaîne de caractères ; assurez-vous simplement que l’ID d’événement dans votre serveur de traitement de webhook corresponde à celui que vous avez saisi dans l’Adapty Dashboard. Vous ne pouvez pas laisser l’ID d’événement vide pour les événements activés.

5. Les champs et options supplémentaires ne sont pas obligatoires ; utilisez-les selon vos besoins :

Paramètre	Description
Send Trial Price	Lorsque cette option est activée, Adapty inclut le prix de l’abonnement dans les champs price_local et price_usd pour l’événement Trial Started.
Exclude Historical Events	Permet d’exclure les événements survenus avant que l’utilisateur ait installé l’application avec le SDK Adapty. Cela évite la duplication des événements et garantit des rapports précis. Par exemple, si un utilisateur a activé un abonnement mensuel le 10 janvier et mis à jour l’application avec le SDK Adapty le 6 mars, Adapty ignorera les événements antérieurs au 6 mars et conservera les événements suivants.
Send user attributes	Activez cette option pour envoyer des attributs spécifiques à l’utilisateur, tels que les préférences de langue. Ces attributs apparaîtront dans le champ user_attributes. Consultez Champs d’événement pour plus d’informations.
Send attribution	Activez cette option pour inclure les informations d’attribution (par exemple, les données AppsFlyer) dans le champ attributions. Consultez la section Données d’attribution pour plus de détails.
Send Play Store purchase token	Activez cette option pour recevoir le jeton Play Store nécessaire à la revalidation des achats, si besoin. Son activation ajoute le paramètre play_store_purchase_token à l’événement. Pour en savoir plus sur son contenu, consultez la section Jeton d’achat Play Store.

6. N’oubliez pas de cliquer sur le bouton Save pour confirmer les modifications.

Dès que vous cliquez sur Save, Adapty envoie une demande de vérification et attend la réponse de votre serveur.

Choisissez les événements à envoyer et mappez les noms d’événements

Choisissez les événements que vous souhaitez recevoir sur votre serveur en activant le bouton correspondant. Si vos noms d’événements diffèrent de ceux utilisés dans Adapty et que vous devez les conserver tels quels, vous pouvez configurer le mapping en remplaçant les noms d’événements Adapty par défaut par les vôtres dans la section Events names de la page Integrations -> Webhooks.

Le nom de l’événement peut être n’importe quelle chaîne de caractères. Vous ne pouvez pas laisser les champs vides pour les événements activés. Si vous avez accidentellement supprimé le nom d’un événement Adapty, vous pouvez toujours le retrouver dans la rubrique Événements à envoyer aux intégrations tierces.

Gérer les événements webhook

Les webhooks sont généralement envoyés dans les 5 à 60 secondes suivant l’événement. Les événements d’annulation, en revanche, peuvent prendre jusqu’à 2 heures à être délivrés après qu’un utilisateur a annulé son abonnement.

La livraison des webhooks par Adapty est de type « au moins une fois » : chaque événement fait l’objet d’au moins une tentative de livraison, et Adapty relance en cas d’échec plutôt que d’abandonner. Si le code de statut renvoyé par votre serveur est en dehors de la plage 200-404, Adapty relance la livraison avec un délai exponentiel. La première nouvelle tentative a lieu environ 1 minute après l’échec initial, et l’intervalle double à chaque tentative suivante — jusqu’à 9 tentatives réparties sur 24 heures. Nous vous recommandons de configurer votre webhook pour n’effectuer qu’une validation de base du corps de l’événement reçu d’Adapty avant de répondre. Si votre serveur ne peut pas traiter l’événement et que vous ne souhaitez pas qu’Adapty retente la livraison, utilisez un code de statut compris dans la plage 200-404. De plus, traitez toute tâche longue de manière asynchrone et répondez rapidement à Adapty. Si Adapty ne reçoit pas de réponse dans les 10 secondes, la tentative est considérée comme un échec et sera relancée.

Les événements ne sont pas garantis d’arriver dans l’ordre — consultez les Champs d’événement pour savoir comment les trier et les dédoublonner vous-même.

Livraison mise en pause après des échecs répétés

Lorsque la majorité des livraisons récentes vers votre endpoint échouent, Adapty suspend la livraison des webhooks pour votre application. Un échec est défini de la même façon que pour les nouvelles tentatives : un code de statut de réponse en dehors de la plage 200-404, une erreur de connexion, ou aucune réponse dans les 10 secondes. Pendant la suspension, Adapty n’envoie pas les nouveaux événements à votre endpoint et ne les renvoie pas ultérieurement. Ces événements affichent le statut Sending failed, même si votre serveur n’a jamais reçu de requête. Après un délai de récupération, Adapty envoie l’événement suivant pour tester l’endpoint. Si cette livraison réussit, la livraison normale reprend. Si elle échoue, la livraison est à nouveau suspendue avec un délai de récupération plus long.

La demande de vérification qu’Adapty envoie lorsque vous cliquez sur Save ne passe pas par ce pipeline de livraison, elle peut donc réussir même si la livraison est en pause.

Pour maintenir la livraison active, répondez avec un statut 2xx à chaque événement, y compris les événements que votre serveur ne peut pas encore associer à un utilisateur, et traitez-les de votre côté.