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

Envoyez des événements depuis Stripe vers des endpoints de webhook et des services dans le cloud.

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.

En outre, vous pouvez utiliser les événements légers créés par les endpoints de l’API v2. Les SDK de l’API v2 incluent des outils d’aide qui permettent à votre application de récupérer le dernier état d’un objet à partir de Stripe.

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

Stripe génère des données d’événement pour vous informer de l’activité de votre compte.

Lorsqu’un événement se produit, Stripe génère un nouvel objet Event. Une fois que votre destination a reçu cet objet Event, votre application peut exécuter des actions dans le back-end (par exemple, appeler l’API de votre fournisseur pour prévoir une livraison quand vous recevez un événement payment_intent.succeeded). Nous proposons deux types d’objets Event différents :

Événements légers : ces événements incluent uniquement l’ID des objets concernés. Ils sont générés par les API v2 endpoints. Les API v1 endpoints génèrent également des événements légers. Voir la liste complète des événements légers.
Événements instantanés : ces événements fournissent un aperçu cohérent de l’objet qui a été modifié et sont uniquement générés par API v1 endpoints. Ils peuvent inclure une propriété previous_attributes indiquant la modification, le cas échéant. Consultez la liste complète des événements instantanés.

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

Caractéristiques	Événements instantanés	Événements légers
Créé par	Modification de l’état des ressources de API v1	Modification de l’état des ressources de API v2
Payload	Large : inclut un aperçu de l’objet API associé à l’événement	Small : inclut uniquement un ID de l’objet API associé à l’événement
Accéder à des données supplémentaires pour traiter l’événement.	Récupérer la dernière définition d’objet à partir de l’API. La définition de l’objet incluse dans la charge utile de l’événement peut être obsolète au moment où vous traitez l’événement.	Récupérer le dernier objet à partir de l’API ou récupérez l’événement complet à partir de `v2/events`. La charge utile complète de l’événement peut inclure des informations supplémentaires sur l’événement. Par exemple, la charge utile d’un événement `v1.billing.meter.error_report_triggered` comprend des informations sur les types et la fréquence des erreurs générées.
Saisie du SDK	Non saisi	Saisi
Gestion des versions	Versionné par version d’API	Non versionné, ce qui vous permet de mettre à niveau votre intégration sans modifier la configuration de votre endpoint de webhook

Une seule requête d’API peut entraîner la création de plusieurs événements. Par exemple, la création d’un nouvel abonnement pour un client peut se traduire par la génération des événements customer.subscription.created et payment_intent.succeeded. Sélectionnez les événements auxquels vous souhaitez vous abonner pour chaque destination d’événements.

Événements légers

Vous pouvez accéder aux événements légers via l’espace de noms API v2. Ces événements ont un modèle d’autorisation plus détaillé et leur charge utile ne contient aucune donnée de la version API, seulement les ID des objets associés à l’événement. Cela facilite la mise à jour des intégrations qui reçoivent des événements et sont conçues avec un SDK Stripe bien saisi. Les événements légers :

Inclure une propriété data qui peut inclure des informations supplémentaires sur l’événement.
Sont entièrement saisis dans les SDKs for API v2.

Vous pouvez récupérer des objets Event pour chaque notification à partir de l’endpoint /v2/core/events. Ces objets API incluent la propriété data qui peut comporter des informations supplémentaires sur l’événement léger.

Prévenir les erreurs d’application

Si votre application a besoin d’un objet API correspondant à un événement (par exemple, l’objet Meter), vous devez appeler l’API Stripe pour accéder au dernier état de l’objet. Bien que cette méthode nécessite un appel de réseau supplémentaire à Stripe, elle permet d’éviter les erreurs d’application causées par des données d’objet obsolètes (du fait par exemple de conditions d’accès concurrentes). Les SDKs for API v2 contiennent des méthodes de support qui vous permettent de récupérer les enregistrements associés à un événement.

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

Voici un exemple d’événement v1.billing.meter.error_report_triggered. Le champ related_object inclut l’id de l’objet, mais n’inclut pas l’objet enregistré lui-même.

{
  "id": "evt_test_65R9Ijk8dKEYZcXeRWn16R9A7j1FSQ3w3TGDPLLGSM4CW0",
  "object": "v2.core.event",
  "type": "v1.billing.meter.error_report_triggered",
  "livemode": false,
  "created": "2024-09-17T06:20:52.246Z",
  "related_object": {
    "id": "mtr_test_61R9IeP0SgKbYROOx41PEAQhH0qO23oW",
    "type": "billing.meter",
    "url": "/v1/billing/meters/mtr_test_61R9IeP0SgKbYROOx41PEAQhH0qO23oW"
  }
}

Exemple de charge utile d’un é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é :

{
  "id": "evt_1NG8Du2eZvKYlo2CUI79vXWy",
  "object": "event",
  "api_version": "2019-02-19",
  "created": 1686089970,

Récupérer les informations supplémentaires associées à un événement léger

Il existe deux types d’informations que vous pouvez récupérer concernant un événement léger :

Définition de ressource d’un objet associé : chaque événement léger détaille un événement spécifique en lien avec un objet Stripe. 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 événement v1.billing.meter.error_report_triggered, fetchRelatedObject() récupère la version actuelle de l’objet meter qui a déclenché un rapport d’erreur.
Champs supplémentaires de charge utile de l’événement : les événements légers peuvent contenir des données contextuelles supplémentaires qui ne peuvent être récupérées qu’avec l’API. Utilisez l’appel retrieve() avec l’ID de l’événement léger pour récupérer ces champs supplémentaires de charge utile. Par exemple, la récupération d’un événement v1.billing.meter.error_report_triggered avec l’API renvoie un hachage de data supplémentaires. Ce hachage comprend des champs contextuels sur les erreurs déclenchées, tels que l’heure à laquelle l’erreur de validation s’est produite, une liste d’exemples de messages d’erreur et le nombre d’erreurs de validation.

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 :

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énement. Une fois désactivée, Stripe cesse d’envoyer des événements vers cette destination. Une fois réactivée, l’envoi d’événements vers cette destination reprend.