# Intégration à l'aide d'événements Envoyez des événements depuis Stripe vers des endpoints de webhook et des services dans le cloud. > [Les événements légers ](https://docs.stripe.com/event-destinations.md#thin-events) pour les ressources de l’API v1 est disponible en version bêta privée. Vous pouvez les utiliser pour rationaliser les mises à niveau d’intégration sans modifier la configuration de votre webhook. Auparavant, les événements légers ne prenaient en charge que les ressources API v2. [En savoir plus et faire une demande d’accès](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog). Configurez une destination d’événements pour envoyer des événements Stripe vers plusieurs types de destinations, dont des endpoints webhook, [Amazon EventBridge](https://docs.stripe.com/event-destinations/eventbridge.md) et [Azure Event Grid](https://docs.stripe.com/event-destinations/eventgrid.md). Vous pouvez recevoir des événements dans l’un des cas suivants : - [Événements instantanés](https://docs.stripe.com/event-destinations.md#choosing-event-format) autonomes pour une vue ponctuelle de vos ressources - Des [événements légers](https://docs.stripe.com/event-destinations.md#thin-events) et peu volumineux pour vous garantir de toujours agir sur les données les plus récentes, ce qui contribue à simplifier votre processus de mise à niveau d’intégration. ## 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](https://docs.stripe.com/event-destinations/eventbridge.md), à un abonnement Azure à l’aide [d’Azure Event Grid](https://docs.stripe.com/event-destinations/eventgrid.md), ou transmettez-les à un endpoint HTTPS à l’aide des [endpoints webhook](https://docs.stripe.com/webhooks.md). ## Présentation des événements Lorsqu’un événement se produit, Stripe génère un nouvel objet `Event`. Une seule requête API peut entraîner la création de plusieurs événements. Par exemple, la création d’un nouvel abonnement pour un client peut entraîner des événements `customer.subscription.created` et `payment_intent.succeeded`. Pour les intégrations par voie programmatique, nous vous recommandons de configurer une destination d’événements pour recevoir ces événements au fur et à mesure qu’ils se produisent. La façon dont l’événement est structuré et envoyé à votre destination dépend du format que vous choisissez de recevoir. Nous proposons deux types d’objets `Event` différents : - [Événements légers](https://docs.stripe.com/api/v2/events.md) : lorsqu’il est transmis à la destination de votre événement, un événement léger se présente sous la forme d’une notification d’événement allégée qui ne comprend que l’ID des objets concernés. Vous pouvez effectuer un appel à l’API ultérieur pour récupérer l’objet `Événement` complet ou le dernier état des ressources associées. Ceux-ci sont générés par API v2 endpoints . Consultez la [liste complète des événements légers](https://docs.stripe.com/api/v2/core/events/event-types.md). - [Événements instantanés](https://docs.stripe.com/api/events.md) : lorsqu’ils sont envoyés à votre destination, un événement instantané arrive en tant qu’objet `Event` complet avec un instantané cohérent de la ressource qui a changé. Étant donné que ces données peuvent être obsolètes au moment où vous les traitez, nous vous recommandons de récupérer la dernière version de la ressource à partir de l’API. Contrairement aux notifications d’événements légers, les événements instantanés envoyés sont versionnés, ce qui vous oblige à gérer les versions à la fois sur votre destination d’événement Stripe et sur votre client. Ces événements sont uniquement générés par API v1 endpoints. Ils incluent une propriété `previous_attributes` qui indique la modification, le cas échéant. Consultez la [liste complète des événements instantanés](https://docs.stripe.com/api/events/types.md). ### Choisir un format Utilisez des événements légers lorsque : - L’intégrité des données est essentielle, et votre formulaire d’inscription doit agir sur les informations les plus récentes. - Vous souhaitez simplifier le contrôle des versions en gérant les mises à niveau uniquement côté client. - Vous développez une application moderne et sécurisée au niveau des types et souhaitez profiter des avantages du typage SDK. Utilisez des événements instantanés lorsque : - Vous devez vérifier les champs spécifiques qui ont changé sans effectuer d’appel à l’API ultérieur. - Votre intégration nécessite une vue ponctuelle de la définition des ressources et peut tolérer le traitement de données éventuellement cohérentes. 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 | API v2 changements d’état des ressources | | Charge utile livrée | **Large** : inclut un aperçu de l’objet API associé à l’événement | **Small** : inclut un ID de l’objet API lié à l’événement dans une notification d’événement léger | | Accès aux 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érez le dernier objet de l’API ou récupérez l’[événement](https://docs.stripe.com/api/v2/events.md) complet à partir de `v2/events`. La charge utile de l’événement complet peut inclure des détails supplémentaires sur l’événement. Par exemple, la charge utile d’un événement `v1.billing.meter.error_report_triggered` inclut des informations sur les types et la fréquence des erreurs levé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 | | API pour afficher les événements | [API Events v1](https://docs.stripe.com/api/events.md) | [API Events v2](https://docs.stripe.com/api/v2/events.md) | ### Exemple de charge utile de notification d’événement léger Voici un exemple d’événement `v2.core.account.updated` de type léger. Le champ `related_object` inclut l’`id` de l’objet, le champ `reason` indique ce qui a déclenché l’événement, et le champ `changes` montre ce qui a été modifié sur l’objet. ```json { "id": "evt_test_65UIRNU7G1XbhCfOim416TgmEI4ASQ3jHxXt8RFwXoeVwO", "object": "v2.core.event", "type": "v2.core.account.updated", "livemode": false, "created": "2026-03-09T13:00:28.435Z", "context": null, "reason": { "type": "request", "request": { "id": "req_v2y9y15XqG3Futmjg", "idempotency_key": "ik_TgmEI3jHxXt8RFw4jS7ve2QcAReDQWBjPAkAEUm" } }, "related_object": { "id": "acct_1T93Q4Pmpb34Vto6", "type": "v2.core.account", "url": "/v2/core/accounts/acct_1T93Q4Pmpb34Vto6" }, "data": {}, "changes": { "before": { "display_name": "Example Account" }, "after": { "display_name": "Updated Example Account" } } } ``` ### Exemple de charge utile d’é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é : ```json { "id": "evt_1NG8Du2eZvKYlo2CUI79vXWy", "object": "event", "api_version": "2019-02-19", "created": 1686089970, "data": { "object": { "id": "seti_1NG8Du2eZvKYlo2C9XMqbR0x", "object": "setup_intent", "application": null, "automatic_payment_methods": null, "cancellation_reason": null, "client_secret": "seti_1NG8Du2eZvKYlo2C9XMqbR0x_secret_O2CdhLwGFh2Aej7bCY7qp8jlIuyR8DJ", "created": 1686089970, "customer": null, "description": null, "flow_directions": null, "last_setup_error": null, "latest_attempt": null, "livemode": false, "mandate": null, "metadata": {}, "next_action": null, "on_behalf_of": null, "payment_method": "pm_1NG8Du2eZvKYlo2CYzzldNr7", "payment_method_options": { "acss_debit": { "currency": "cad", "mandate_options": { "interval_description": "First day of every month", "payment_schedule": "interval", "transaction_type": "personal" }, "verification_method": "automatic" } }, "payment_method_types": [ "acss_debit" ], "single_use_mandate": null, "status": "requires_confirmation", "usage": "off_session" } }, "livemode": false, "pending_webhooks": 0, "request": { "id": null, "idempotency_key": null }, "type": "setup_intent.created" } ``` ## Utilisation d’événements légers Intégrez les événements légers en utilisant la notification d’événement envoyée à votre destination pour récupérer davantage de détails à partir de l’API. ### Traitement de la notification d’événement La notification initiale contient un minimum de données. Choisissez l’une des trois approches lors du traitement de la notification événement, en fonction des informations requises par votre intégration : 1. **Récupérer l’événement complet** : utilisez la méthode `fetchEvent()` pour récupérer l’objet `Event` complet lorsque vous avez besoin de plus d’informations que ne le fournit le dernier état de l’objet associé. L’objet événement complet peut inclure deux types de données supplémentaires : - Informations contextuelles sur l’événement lui-même, disponibles dans le hachage de `data`. Par exemple, un événement `v1.billing.meter.error_report_triggered` inclut des détails sur les types et le récapitulatif des erreurs de validation dans ce champ. - Les valeurs précédentes de tous les attributs qui ont changé sur la ressource, disponibles dans le hachage des `changes`. Le tableau suivant détaille les données supplémentaires disponibles dans l’objet [événement](https://docs.stripe.com/api/v2/events.md) complet par rapport à la notification initiale : | Nom de la propriété | Notification d’événement | Evènements | | -------------------------- | ------------------------ | ---------- | | Type d’événement | ✅ | ✅ | | D de la ressource associée | ✅ | ✅ | | L’ID de l’événement | ✅ | ✅ | | Horodatage créé | ✅ | ✅ | | Motif | ✅ | ✅ | | Modifications | ❌ | ✅ | | Données | ❌ | ✅ | 1. **Récupérer le dernier état de l’objet associé** : 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 `v1.billing.meter.error_report_triggered event`, `fetchRelatedObject()` récupère la version actuelle de l’objet du compteur qui a déclenché un rapport d’erreur. 1. **traiter la notification immédiatement** : si le type d’événement et l’ID de la ressource dans la notification sont suffisants pour votre cas d’usage, vous pouvez le traiter sans effectuer d’appel à l’API 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 : #### Java ```java com.stripe.model.EventNotification eventNotification = client.parseEventNotification(payload, signatureHeader, endpointSecret); com.stripe.model.v2.Event event = client.v2().core().events().retrieve(eventNotification.getId()); if (event instanceof V1BillingMeterErrorReportTriggeredEvent) { V1BillingMeterErrorReportTriggeredEvent postedEvent = (V1BillingMeterErrorReportTriggeredEvent) event; // On each type of event, the Stripe library provides a "fetchRelatedObject" method // that performs a network request to Stripe to fetch the latest version // of the object directly associated with the event, in this case, an // "Meter" object. Meter op = postedEvent.fetchRelatedObject(); } ``` ### Saisie du SDK Les événements légers et leurs notifications sont entièrement saisis dans les SDK. - **Notification d’événement** : la charge utile initiale et légère envoyée à votre destination d’événement est de type `{EventType}EventNotification`. - **Événement** : après avoir récupéré l’événement complet de l’API avec la valeur `fetchEvent()`, l’objet résultant est saisi comme `{EventType}Event`. ## Autorisations d’événement Pour afficher un événement dans le Dashboard, attribuez le [rôle d’administrateur ou de développeur](https://docs.stripe.com/get-started/account/teams/roles.md) à votre compte utilisateur. Pour récupérer un événement via l’API, utilisez soit une [clé API secrète](https://docs.stripe.com/keys.md#create-api-secret-key), qui vous permet de visualiser tous les types d’événements par défaut, soit une [clé API limitée](https://docs.stripe.com/keys.md#create-restricted-api-secret-key) 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 currency](https://docs.stripe.com/api/v2/core/events/retrieve.md) et [List events](https://docs.stripe.com/api/v2/core/events/list.md) 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](https://dashboard.stripe.com/webhooks) dans Workbench ou utilisez l’[API Event Destinations](https://docs.stripe.com/api/v2/event-destinations/.md). ## Désactiver une destination d’événements Vous pouvez désactiver une destination d’événements. Une fois que vous l’avez désactivée, Stripe cesse d’envoyer des événements vers cette destination. Une fois que vous avez réactivé une destination, Stripe recommence à lui envoyer des événements.