Envoyer des événements à Amazon EventBridge

Amazon EventBridge est un service sans serveur et piloté par les événements fourni par AWS. Il permet de connecter vos applications grâce à l’intégration, la transformation et la livraison d’événements. L’intégration à EventBridge à l’aide d’une destination d’événement permet de recevoir les données d’événement de Stripe directement dans votre compte AWS, au lieu de gérer vous-même le trafic et la logique de code d’intégration. À la réception des événements, EventBridge peut les acheminer vers 20 cibles prises en charge pour traiter ou déclencher des automatisations commerciales.

Envoyer des événements à Amazon EventBridge

Suivez les étapes ci-dessous pour recevoir des événements dans EventBridge. Cela implique la création d’une destination d’événement dans Workbench et la configuration d’EventBridge dans la console de gestion AWS.

Ajouter une nouvelle destination d'événement

Workbench

Envoyer des événements dans votre environnement de test

Utilisez votre compte de production ou vos environnements de test pour envoyer des événements à Amazon EventBridge.

Créez une destination d’événement à l’aide de Workbench dans le Dashboard ou par programmation avec l’API.

Dashboard

API

Pour créer une destination d’événement dans le Dashboard :

1. Ouvrez l’onglet Webhooks dans Workbench.
2. Cliquez sur Créer une destination.
3. Sélectionnez l’emplacement d’où vous souhaitez recevoir les événements. Stripe prend en charge deux types de configurations : Votre compte et Comptes connectés. Sélectionnez Compte pour écouter les événements de votre propre compte. Si vous avez créé une application Connect et que vous souhaitez écouter les événements de vos comptes connectés, sélectionnez Comptes connectés.

Écouter des événements à partir d'une destination d'événement de l'organisation

Si vous créez une destination d’événement dans un compte d’organisation, sélectionnez Comptes pour écouter les événements des comptes de votre organisation. Si des plateformes Connect figurent parmi les membres de vos organisations et que vous souhaitez écouter les événements de tous les comptes connectés des plateformes, sélectionnez Comptes connectés.

1. Sélectionnez les types d’événements que vous souhaitez que cette destination reçoive. Cliquez ensuite sur Continuer.
2. Sélectionnez Amazon EventBridge comme type de destination, puis cliquez sur Continuer.
3. Saisissez les informations suivantes :
   • Identifiant du compte AWS : le compte AWS qui héberge votre instance EventBridge pour la réception des événements.
   • Région AWS : région AWS qui héberge votre instance EventBridge pour la réception des événements.
   • (Facultatif) Nom de la destination : nom unique attribué à cette ressource de destination d’événements dans Stripe. Si vous ne fournissez pas de nom, nous en générons un pour vous aléatoirement. Vous pourrez le modifier ultérieurement.
   • (Facultatif) Description : une description qui distingue votre instance de destination d’événements. Vous pourrez modifier ce choix ultérieurement.
4. Cliquez sur Créer une destination.

Enregistrer un nouveau webhook dans l’onglet Webhooks

Associer la source de l'événement partenaire

AWS Console

Après avoir configuré une destination d’événement, Stripe crée une source d’événements partenaire dans le compte et dans la région AWS que vous avez indiqués lors de la configuration. Pour commencer à recevoir des événements, vous devez associer cette source d’événements à un bus d’événements dans les 7 jours suivant la création de la destination d’événements. Si vous ne l’associez pas au cours de cette période, Amazon supprime automatiquement la source d’événements en attente. Après la suppression d’une source d’événements, votre destination d’événements Stripe est automatiquement désactivée et vous devez créer une nouvelle destination pour recevoir des événements.

1. Sous EventBridge dans votre console AWS, accédez à la page Sources d’événements partenaires figurant dans la section Intégration du panneau de gauche.

1. Utilisez la liste déroulante Région située en haut de la console pour sélectionner la région que vous avez choisie lorsque vous avez configuré la destination d’événements dans Workbench.

1. Choisissez la nouvelle source d’événements partenaire créée dans la liste déroulante. Pour trouver le champ ARN de la source d’événements dans Workbench, sélectionnez votre destination d’événements. Votre source partenaire correspond à la partie de l’ARN indiquant event-source/aws.partner/stripe.com/{UNIQUE_ID}. Ensuite, cliquez sur Associer au bus d’événements.

1. Le cas échéant, sélectionnez les autorisations que vous souhaitez accorder pour ce bus d’événements, puis cliquez sur Associer.

Créer des règles EventBridge

AWS Console

EventBridge regroupe et achemine les événements en fonction des règles que vous avez définies. Après avoir créé une destination d’événements et associé sa source d’événements partenaire à un bus d’événements, vous devez définir des règles pour vous assurer qu’EventBridge sait comment traiter les événements qu’il reçoit au niveau du bus d’événements. Vous pouvez répéter ces étapes plusieurs fois pour définir plusieurs règles.

1. Accédez à la console de gestion AWS, puis cliquez sur Règles.

1. Cliquez sur Créer une règle, puis donnez un nom et une description à la règle.

1. Sélectionnez votre bus d’événement dans le menu déroulant. Pour trouver votre bus d’événements, accédez à Workbench, sélectionnez votre destination dans l’onglet Webhooks, puis affichez le champ ARN de la source de l’événement, qui porte le même nom que l’ARN de votre source d’événements. Cliquez ensuite sur Suivant.
2. Sous Source de l’événement, sélectionnez Événements AWS ou Événements partenaires EventBridge, car les événements Stripe sont des événements partenaires.

1. (Facultatif) Incluez un exemple d’événement Stripe.
2. Sous Méthode de création, choisissez Utiliser un modèle pour utiliser un modèle prédéfini. Vous pouvez également créer un modèle d’événement personnalisé.

1. Sous Modèle d’événement, sélectionnez Partenaires EventBridge comme Source de l’événement.
2. Sous Modèle d’événement, sélectionnez Stripe comme Partenaire.
3. Sélectionnez le type d’événement pour lequel vous souhaitez créer une règle, ou sélectionnez Tous les événements pour appliquer cette règle à tous les types d’événements, puis cliquez sur Suivant.
4. Sélectionnez la cible vers laquelle vous souhaitez que cette règle envoie des événements, puis cliquez sur Suivant.

Recommandation

Nous vous recommandons de créer une cible CloudWatch Logs pour chaque bus d’événements afin d’activer la surveillance de votre destination d’événements. Envisagez d’utiliser d’autres modèles d’architecture courants avec les événements EventBridge et Stripe.

1. Ajoutez des balises facultatives, puis cliquez sur Suivant.
2. Vérifiez votre règle et apportez des modifications si nécessaire, puis cliquez sur Créer une règle.

Vos événements Stripe vont maintenant être livrés à EventBridge ainsi qu’aux cibles correspondantes définies dans votre règle.

Déclencher des événements de test

Pour envoyer des événements de test, déclenchez un type d’événement auquel votre destination d’événement est abonnée en créant manuellement un objet dans le Dashboard Stripe. Découvrez comment déclencher des événements avec Stripe pour VS Code.

stripe trigger payment_intent.succeeded
Running fixture for: payment_intent
Trigger succeeded! Check dashboard for event details.

Comportements des envois d’événements

Cette section vous aide à comprendre les différents comportements auxquels vous pouvez vous attendre concernant la manière dont Stripe envoie des événements à Amazon EventBridge.

Retentatives automatiques

Stripe tente de livrer des événements à votre destination pendant un maximum de trois jours avec un recul exponentiel en mode production. Le cas échéant, vous pouvez voir quand la prochaine tentative aura lieu dans l’onglet Événements envoyés de votre destination d’événement. Les livraisons d’événements créées dans un environnement de test sont relancées trois fois en l’espace de quelques heures. Si votre destination a été désactivée ou supprimée lorsque nous effectuons une nouvelle tentative de remise, nous annulons toute relance ultérieure de cet événement. Toutefois, si vous désactivez puis réactivez la destination de l’événement avant que nous ne puissions effectuer la relance, les tentatives ultérieures seront toujours visibles.

Retentatives manuelles

Il existe deux façons de relancer manuellement des événements :

• Dans le Dashboard Stripe, cliquez sur Renvoyer lorsque vous consultez un événement spécifique. Cette relance fonctionne jusqu’à 15 jours après la création de l’événement.
• À l’aide de la CLI Stripe, exécutez la commande stripe events resend <event_id> --webhook-endpoint=<endpoint_id>. Cette relance fonctionne jusqu’à 30 jours après la création de l’événement.

Ordre des événements

Stripe ne garantit pas la remise des événements dans l’ordre dans lequel ils ont été générés. Par exemple, la création d’un abonnement peut générer les événements suivants :

• customer.subscription.created
• invoice.created
• invoice.paid
• charge.created (si un paiement a lieu)

Assurez-vous que la destination de votre événement ne dépend pas de la réception des événements dans un ordre spécifique. Soyez prêt à gérer correctement leur livraison. Vous pouvez également utiliser l’API pour récupérer les éventuels objets manquants. Par exemple, vous pouvez récupérer les objets invoice, charge et subscription avec les informations de invoice.paid si vous recevez cet événement en premier.

Gestion des versions de l’API

Lorsque l’événement survient, la version de l’API dans les paramètres de votre compte détermine la version de l’API, et par extension la structure d’un événement, envoyées à votre destination. Par exemple, si votre compte utilise une ancienne version d’API, comme 2015-02-16, et que vous modifiez la version de l’API pour une requête spécifique avec le contrôle de version, l’objet Event généré et envoyé à votre destination est toujours basé sur la version de l’API du 16/02/2015. Vous ne pouvez pas modifier les objets Event une fois qu’ils ont été créés. Par exemple, si vous mettez à jour un paiement, l’événement de paiement d’origine reste inchangé. Par conséquent, les mises à jour apportées par la suite à la version de l’API de votre compte ne modifient pas de manière rétroactive les objets Event existants. La récupération d’un ancien Event par l’appel à /v1/events à l’aide d’une version récente de l’API n’a pas non plus de conséquence sur la structure de l’événement reçu. Vous pouvez définir les destinations des événements de test sur votre version d’API par défaut ou sur la version la plus récente de l’API. L’objet Event envoyé à la destination est structuré en fonction de la version spécifiée pour la destination de l’événement.

État de la destination d’événement

Plusieurs états décrivent l’état de préparation des destinations Amazon EventBridge à recevoir des événements :

• Actif : vous avez associé avec succès la destination d’événements à un bus d’événements. Si vous configurez correctement une règle EventBridge, vous recevez les événements dans les consommateurs d’événements de votre choix.
• Désactivé : Stripe n’envoie pas d’événements à Amazon EventBridge. Votre destination sera à cet état soit parce que vous l’avez désactivée manuellement, soit parce que Stripe l’a désactivée automatiquement en raison d’une mauvaise configuration d’AWS.
• En attente : une fois que la destination d’événements a créé une source d’événements partenaire dans AWS, vous devez associer cette source à un bus d’événements. La destination reste à l’état « En attente » et ne reçoit pas d’événements tant que vous n’effectuez pas cette association. À ce moment-là, l’état de la destination devient « Active ».

Structure d’événement

EventBridge utilise sa propre structure d’événement qui enveloppe l’objet JSON de l’attribut event Stripe dans un champ detail de niveau supérieur.

Cet exemple montre une charge utile d’événement customer.created d’EventBridge :

{
   "version":"0",
   "id":"17e8dff5-d6cd-3770-ace9-aeac02b6ac3f",
   "detail-type":"customer.created",
   "source":"aws.partner/stripe.com/ed_61PgtRTG5aTCIz98516PLsRGLISQK0Otk6FWKjBrcDia",
   "account":"506417113029",
   "time":"2024-03-07T18:27:56Z",
   "region":"us-west-2",
   "resources":[

Prise en charge des types d’événements pour lesquels Stripe attend une réponse

Stripe envoie la plupart des types d’événements de manière asynchrone ; cependant, pour certains types d’événements, Stripe attend une réponse. La présence ou l’absence d’une réponse de la part de la destination d’événements influence directement les actions de Stripe concernant ces types d’événements spécifiques.

Les destinations Amazon EventBridge offrent une prise en charge limitée des types d’événements nécessitant une réponse :

• Vous ne pouvez pas vous abonner au type d’événement issuing_authorization.request pour les destinations Amazon EventBridge. Configurez plutôt un endpoint de webhook pour vous abonner à ce type d’événement. Utilisez issuing_authorization.request pour autoriser les demandes d’achat en temps réel. Pour ce faire, votre destination doit approuver ou refuser les demandes en répondant à l’événement. EventBridge traite la réponse à Stripe avant de l’envoyer à vos consommateurs. Par conséquent, ce type de destination ne peut pas utiliser ce type d’événement pour autoriser des paiements.
• Vous pouvez vous abonner à checkout_sessions.completed lorsque vous utilisez Amazon EventBridge. Cependant, cela ne vous permet pas de gérer le comportement de redirection lorsque vous intégrez Checkout directement dans votre site Web ou que vous redirigez les clients vers une page de paiement hébergée par Stripe. L’envoi d’un événement checkout_sessions.completed à Amazon EventBridge n’affectera pas le comportement de redirection. Pour influencer le comportement de redirection de Checkout, traitez ce type d’événement avec un endpoint de webhook.

Modèles d’architecture communs avec les événements EventBridge et Stripe

Tenez compte des modèles architecturaux suivants lorsque vous utilisez Amazon EventBridge avec Stripe :

• Déclenchement de fonctions sans serveur avec Lambda pour définir des automatisations commerciales : envoyez des événements Stripe depuis EventBridge vers Lambda pour déclencher des fonctions de calcul sans serveur, telles que la création d’une étiquette de livraison suite à un paiement effectué.
• Surveillance des événements avec CloudWatch : envoyez des événements depuis EventBridge vers CloudWatch Logs pour stocker les événements sous forme de données de logs, que vous pourrez analyser et rechercher de manière interactive. Surveillez les comportements d’utilisation et les erreurs avec CloudWatch. Envisagez de configurer des alertes en cas d’erreur (par exemple, en cas de non-respect d’une règle EventBridge).
• Déclenchement de workflows à faible code et sans code avec Step Functions : envoyez des événements vers un workflow StepFunction qui déclenche vos scénarios métier, par exemple pour informer vos clients que leur période d’essai touche à sa fin.
• Distribution d’événements vers des systèmes internes avec Simple Notification Service (SNS) ou Simple Queue Service (SQS) : envoyez des événements Stripe vers SNS ou vers SQS afin de distribuer les données d’événements Stripe à vos équipes internes pour stockage et traitement.