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

Effectuez les actions ci-dessous pour recevoir des événements dans EventBridge. Cela implique la création d’une nouvelle destination d’événements dans Workbench et la configuration d’EventBridge dans l’AWS Management Console.

Ajouter une nouvelle destination d'événements

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 Destinations d’événements dans Workbench.
2. Cliquez sur Créer une destination.
3. Sélectionnez l’endroit 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.
4. Sélectionnez les types d’événements que vous souhaitez que cette destination reçoive, puis cliquez sur Continuer.
5. Sélectionnez Amazon EventBridge comme type de destination, puis cliquez sur Continuer.
6. 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 pour 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 : description qui distingue votre instance de destination d’événements. Vous pourrez la modifier ultérieurement.
7. Cliquez sur Créer une destination.

Créer un nouveau webhook dans l’onglet Destinations d’événements

Associer la source d'événements partenaire

Console AWS

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. Dans votre console AWS, sous EventBridge, accédez à la page Partner event sources qui figure dans la section Integration 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 une ou plusieurs règles EventBridge

Console AWS

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 Rules.

1. Cliquez sur Create rule, puis saisissez le nom de la règle ainsi qu’une description.

1. Sélectionnez votre bus d’événements dans la liste déroulante. Pour trouver votre bus d’événements, accédez à Workbench, sélectionnez votre destination dans l’onglet Destination de l’événement, puis affichez le champ ARN de la source d’événements qui porte le même nom que l’ARN de votre source d’événements. Ensuite, cliquez sur Suivant.
2. Sous Event source, sélectionnez AWS events or EventBridge partner events, car les événements Stripe sont des événements partenaires.

1. (Facultatif) Intégrez un exemple d’événement Stripe.
2. Sous Creation Method, choisissez Use pattern form pour utiliser un modèle de création prédéfini. Vous pouvez également créer un modèle d’événement personnalisé.

1. Sous Event Pattern, sélectionnez EventBridge partners comme Event Source.
2. Sous Event Pattern, sélectionnez Stripe comme Partner.
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 webhook est abonné en créant manuellement un objet dans le Dashboard Stripe. Vous pouvez également utiliser la commande suivante dans le Shell Stripe ou dans l’interface de ligne de commande Stripe.

Cet exemple déclenche un événement payment_intent.succeeded :

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

Découvrez comment déclencher des événements avec Stripe pour VS Code.

Comportements de remise 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

There are two ways to manually retry events:

• In the Stripe Dashboard, click Resend when looking at a specific event. This works for up to 15 days after the event creation.
• With the Stripe CLI, run the stripe events resend <event_id> --webhook-endpoint=<endpoint_id> command. This works for up to 30 days after the event creation.

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

La version de l’API dans les paramètres de votre compte au moment de l’événement détermine sa version, et détermine ainsi la structure d’un Event envoyé à votre destination. Par exemple, si votre compte est défini sur une ancienne version d’API telle que celle du 16-02-2015 et que vous modifiez la version d’API pour une demande spécifique avec la gestion des versions, l’objet Event généré et envoyé à votre destination est toujours basé sur la version d’API du 16-02-2015. Vous ne pouvez pas modifier les objets Event après leur création. Par exemple, si vous mettez à jour un paiement, l’événement de paiement d’origine reste inchangé. Par conséquent, les mises à jour ultérieures de la version de l’API de votre compte ne modifient pas rétroactivement les objets Event existants. La récupération d’un ancien Event en appelant /v1/events à l’aide d’une version plus récente de l’API n’a pas non plus d’impact sur la structure de l’événement reçu. Vous pouvez définir les destinations des événements de test en fonction de votre version d’API par défaut ou de la dernière version d’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 courants avec les événements EventBridge et Stripe

Si vous utilisez Amazon EventBridge avec Stripe, envisagez les modèles d’architecture suivants :

• 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.