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

To send test events, trigger an event type that your event destination is subscribed to by manually creating an object in the Stripe Dashboard. Learn how to trigger events with Stripe for 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

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

The API version in your account settings when the event occurs dictates the API version, and therefore the structure of an Event sent to your destination. For example, if your account is set to an older API version, such as 2015-02-16, and you change the API version for a specific request with versioning, the Event object generated and sent to your destination is still based on the 2015-02-16 API version. You can’t change Event objects after creation. For example, if you update a charge, the original charge event remains unchanged. As a result, subsequent updates to your account’s API version don’t retroactively alter existing Event objects. Retrieving an older Event by calling /v1/events using a newer API version also has no impact on the structure of the received event. You can set test event destinations to either your default API version or the latest API version. The Event sent to the destination is structured for the event destination’s specified version.

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