Destinations d'événements

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

Note

Si vous ne voyez pas l’onglet Destinations d’événements dans Workbench ou le Dashboard des développeurs, activez les destinations d’événements dans le paramètre d’aperçu des produits.

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 :

Envoi d’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
Octroi d’un accès à votre utilisateur lorsqu’il effectue des paiements d’abonnement récurrents

Types de destinations 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 l’API v1	Modification de l’état des ressources de l’API v2
Charge utile	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
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 d’assistance 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"
  }
}

Par conséquent, la charge utile d’un événement léger est bien plus petite que celle d’un événement instantané. À titre de comparaison, voici un exemple d’événement instantané invoice.created :

{
  "object": {
    "id": "in_1KnN0G589O8KAxCGfVSpD0Pj",
    "object": "invoice",
    "account_country": "US",

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 relatives aux événements

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

Vous pouvez accéder aux événements créés au cours des 13 derniers mois dans l’onglet Événements de Workbench. Cependant, vous ne pouvez renvoyer ou consulter manuellement que les tentatives d’envoi datant de moins de 15 jours dans la section Événements envoyés. Pour les événements datant de plus de 30 jours, vous pouvez accéder à une synthèse, qui ne comprend que des champs tronqués des données d’origine de l’événement.

Vous pouvez accéder aux événements légers des 30 derniers jours en utilisant Retrieve event et List events API v2 endpoints. Pour accéder aux événements instantanés des 30 derniers jours, utilisez Retrieve event et List event API v1 endpoints.

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 Destinations d’événements 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 cette fonctionnalité désactivée, Stripe cessera d’envoyer des événements vers cette destination. Une fois que vous avez réactivé une destination, Stripe reprend l’envoi des événements vers cette destination.