Intégration à l'aide d'événements

Configurez une destination d’événement pour envoyer des événements Stripe vers plusieurs types de destinations, dont des endpoints de webhook et Amazon EventBridge. Vous pouvez recevoir des événements dans l’un des cas suivants :

• Événements instantanés autonomes pour une vue ponctuelle de vos ressources
• Des événements légers et peu volumineux pour vous garantir de toujours agir sur les données les plus récentes, ce qui contribue à simplifier votre processus de mise à niveau d’intégration.

Cas d’usage

Lors de la création d’intégrations Stripe , vous pouvez faire en sorte que vos applications reçoivent les événements en temps réel depuis vos comptes Stripe, afin de permettre à vos systèmes dans le back-end de répondre et d’exécuter les actions nécessaires en conséquence.

Avec une destination d’événement, Stripe transfère les données d’événement en temps réel depuis votre compte, ce qui vous permet d’exécuter des actions dans le back-end, comme :

• Envoyer une notification aux utilisateurs lorsqu’un client confirme un paiement
• Démarrer un processus interne de rapprochement des litiges lorsqu’un client conteste un paiement
• Accorder l’accès à vos utilisateurs lorsqu’ils effectuent des paiements d’abonnement récurrents

Types de destination pris en charge

Envoyez des événements à un compte AWS à l’aide d’Amazon EventBridge, ou envoyez-les à un endpoint HTTPS par l’intermédiaire d’endpoints de webhook.

Présentation des événements

Lorsqu’un événement se produit, Stripe génère un nouvel objet Événement. Une seule requête API peut entraîner la création de plusieurs événements. Par exemple, la création d’un nouvel abonnement pour un client peut entraîner des événements client.abonnement.created et payment_intent.succeeded. Pour les intégrations par voie programmatique, nous vous recommandons de configurer une destination d’événements pour recevoir ces événements au fur et à mesure qu’ils se produisent. La façon dont l’événement est structuré et envoyé à votre destination dépend du format que vous choisissez de recevoir.

Nous proposons deux types d’objets Événement différents :

• Événements légers : lorsqu’il est transmis à la destination de votre événement, un événement léger se présente sous la forme d’une notification d’événement allégée qui ne comprend que l’ID des objets concernés. Vous pouvez effectuer un appel à l’API ultérieur pour récupérer l’objet Événement complet ou le dernier état des ressources associées. Ceux-ci sont générés par API v2 endpoints . Consultez la liste complète des événements légers.
• Événements instantanés : lorsqu’ils sont envoyés à votre destination, un événement instantané arrive en tant qu’objet Evénement complet avec un instantané cohérent de la ressource qui a changé. Étant donné que ces données peuvent être obsolètes au moment où vous les traitez, nous vous recommandons de récupérer la dernière version de la ressource à partir de l’API. Contrairement aux notifications d’événements légers, les événements instantanés envoyés sont versionnés, ce qui vous oblige à gérer les versions à la fois sur votre destination d’événement Stripe et sur votre client. Ces événements sont uniquement générés par API v1 endpoints. Ils incluent une propriété previous_attributes qui indique la modification, le cas échéant. Consultez la liste complète des événements instantanés.

Choisir un format

Utilisez des événements légers lorsque :

• L’intégrité des données est essentielle, et votre formulaire d’inscription doit agir sur les informations les plus récentes.
• Vous souhaitez simplifier le contrôle des versions en gérant les mises à niveau uniquement côté client.
• Vous développez une application moderne et sécurisée au niveau des types et souhaitez profiter des avantages du typage SDK.

Utilisez des événements instantanés lorsque :

• Vous devez vérifier les champs spécifiques qui ont changé sans effectuer d’appel à l’API ultérieur.
• Votre intégration nécessite une vue ponctuelle de la définition des ressources et peut tolérer le traitement de données éventuellement cohérentes.

Ce tableau présente les différences générales entre les événements légers et les événements instantanés.

Exemple de charge utile de notification d’événement léger

Voici un exemple d’événement v1.billing.meter.error_report_triggered. Le hachage de données ci-dessous remporté ne sera pas accessible dans la notification d’événement envoyée à la destination. Le champ related_object inclut l’ID de l’objet, mais n’inclut pas l’enregistrement de l’objet lui-même.

Exemple de charge utile d’événement instantané

Jetez un œil à l’exemple suivant d’événement instantané setup_intent.created, qui inclut la définition de l’objet telle qu’elle était lorsque l’événement a été déclenché :

Utilisation d’événements légers

Intégrez les événements légers en utilisant la notification d’événement envoyée à votre destination pour récupérer davantage de détails à partir de l’API.

Traitement de la notification d’événement

La notification initiale contient un minimum de données. Choisissez l’une des trois approches lors du traitement de la notification événement, en fonction des informations requises par votre intégration :

1. Récupérer l’événement complet : utilisez la méthode fetchEvent() pour récupérer l’objet Événement complet lorsque vous avez besoin de plus d’informations que ne le fournit le dernier état de l’objet associé. L’objet événement complet peut inclure deux types de données supplémentaires :
   • Informations contextuelles sur l’événement lui-même, disponibles dans le hachage de données. Par exemple, un événement v1.billing.meter.error_report_triggered inclut des détails sur les types et le récapitulatif des erreurs de validation dans ce champ.
   • Les valeurs précédentes de tous les attributs qui ont changé sur la ressource, disponibles dans le hachage des modifications.

Le tableau suivant détaille les données supplémentaires disponibles dans l’objet événement complet par rapport à la notification initiale :

1. Récupérer le dernier état de l’objet associé : utilisez la méthode fetchRelatedObject() pour récupérer la dernière version de l’objet associé à l’événement. Par exemple, si vous recevez un v1.billing.meter.error_report_triggered event, fetchRelatedObject() récupère la version actuelle de l’objet du compteur qui a déclenché un rapport d’erreur.
2. traiter la notification immédiatement : si le type d’événement et l’ID de la ressource dans la notification sont suffisants pour votre cas d’usage, vous pouvez le traiter sans effectuer d’appel à l’API

L’exemple suivant montre comment récupérer la définition de l’objet associé et les champs de données utiles supplémentaires associés à un événement léger :

Saisie du SDK

Les événements légers et leurs notifications sont entièrement saisis dans les SDK.

• Notification d’événement : la charge utile initiale et légère envoyée à votre destination d’événement est de type {EventType}EventNotification.
• Événement : après avoir récupéré l’événement complet de l’API avec la valeur fetchEvent(), l’objet résultant est saisi comme {EventType}Événement.

Autorisations d’événement

Pour afficher un événement dans le Dashboard, attribuez le rôle d’administrateur ou de développeur à votre compte utilisateur. Pour récupérer un événement via l’API, utilisez soit une clé API secrète, qui vous permet de visualiser tous les types d’événements par défaut, soit une clé API limitée en activant l’accès en lecture (Read) pour la ressource du type d’événement concerné. Par exemple, vous pouvez accorder l’accès Read aux ressources payment_intent sur votre clé API limitée pour récupérer payment_intent.succeeded events de façon programmatique.

Rétention des événements

Dans l’onglet Événements de Workbench, vous pouvez accéder aux événements des 13 derniers mois :

• Pour les événements datant de moins de 15 jours, vous pouvez afficher la charge utile complète de l’événement, afficher les tentatives d’envoi et renvoyer manuellement ces événements.
• Pour les événements datant de 16 à 30 jours, vous pouvez accéder à la charge utile complète de l’événement, mais vous ne pouvez pas les renvoyer ni afficher les tentatives d’envoi.
• Pour les événements datant de plus de 30 jours, vous pouvez accéder à un récapitulatif qui comprend uniquement des champs tronqués des données de l’événement d’origine. Le renvoi et l’affichage des tentatives d’envoi ne sont pas disponibles pour ces événements.

Utilisez les API Retrieve Event et List Events pour accéder aux événements avec leur charge utile complète des 30 derniers jours.

Limites des destinations d’événement

Vous pouvez enregistrer un maximum de 16 destinations d’événement dans chaque compte en mode production ou en environnement de test. Lors de l’enregistrement d’une destination d’événement instantané avec une version différente de la version par défaut de votre marchand, vous pouvez inscrire jusqu’à trois destinations d’événement instantané versionnées de manière distincte.

Gérer une destination d’événement

Pour créer, supprimer et mettre à jour une destination d’événement dans le Dashboard, ouvrez l’onglet Webhooks dans Workbench ou utilisez l’API Event Destinations.

Désactiver une destination d’événements

Vous pouvez désactiver une destination d’événements. Une fois que vous l’avez désactivée, Stripe cesse d’envoyer des événements vers cette destination. Une fois que vous avez réactivé une destination, Stripe recommence à lui envoyer des événements.