# Recevez les événements Stripe dans votre endpoint de webhook Écoutez les événements depuis Stripe sur votre endpoint webhook afin que votre intégration puisse déclencher automatiquement des réactions. Vous pouvez créer un endpoint webhook HTTPS pour recevoir des événements. Après avoir enregistré un endpoint webhook, Stripe envoie des données en temps réel à celui-ci lorsque des [événements](https://docs.stripe.com/event-destinations.md#events-overview) se produisent sur votre compte Stripe. Stripe utilise HTTPS pour envoyer les événements webhook à votre application sous la forme d’un payload JSON contenant les informations relatives à l’événement. La réception d’événements webhook vous permet de répondre à des événements asynchrones, par exemple lorsque la banque d’un client confirme un paiement, qu’un client conteste un débit ou qu’un paiement récurrent aboutit. Vous pouvez également recevoir les événements Stripe dans votre infrastructure AWS ou Azure en envoyant directement les événements vers [Amazon EventBridge](https://docs.stripe.com/event-destinations/eventbridge.md) ou [Azure Event Grid](https://docs.stripe.com/event-destinations/eventgrid.md). Suivez les étapes ci-dessous pour commencer à recevoir des événements de webhook dans votre application. Vous pouvez inscrire et créer un endpoint pour gérer plusieurs types d’événements différents en même temps, ou configurer des endpoints individuels pour des événements spécifiques. ## Configurez votre endpoint Utilisez l’[API](https://docs.stripe.com/api/v2/event-destinations.md) ou l’onglet [Webhooks](https://dashboard.stripe.com/webhooks) dans Workbench pour enregistrer l’URL accessible de votre endpoint webhook afin que Stripe sache où envoyer les événements. Vous pouvez enregistrer jusqu’à 16 endpoints webhook auprès de Stripe. Les endpoints webhook enregistrés doivent être des URL HTTPS accessibles publiquement. - Si vous avez un serveur localhost mais ne disposez pas d’une URL HTTPS accessible publiquement, vous pouvez utiliser un outil de tunneling tel que [ngrok](https://ngrok.com/) pour générer une URL HTTPS publique temporaire à des fins de test. - Vous pouvez également [tester localement avec Stripe CLI](https://docs.stripe.com/webhooks.md#local-listener) avant d’enregistrer une URL HTTPS accessible publiquement. ### Format d’URL de webhook L’endpoint de webhook doit être enregistré avec le format d’URL suivant : ``` https:/// ``` Par exemple, si votre domaine est `https://mycompanysite.com` et que la route vers votre endpoint webhook est `@app.route(’/stripe_webhooks’, methods=[’POST’])`, spécifiez `https://mycompanysite.com/stripe_webhooks` comme URL de l’endpoint. ### Créer une destination d’événement pour votre endpoint de webhook #### Dashboard Pour créer un nouvel endpoint de webhook dans le Dashboard : 1. Ouvrez l’onglet [Webhooks](https://dashboard.stripe.com/webhooks) dans Workbench. 2. Cliquez sur **Créer une destination d’événements**. 3. Sélectionnez **Votre compte** pour écouter les événements provenant de votre propre compte. 4. Sélectionnez la version de l’API pour l’objet [events](https://docs.stripe.com/api/events.md) que vous souhaitez utiliser. 5. Sélectionnez les [types d’événements](https://docs.stripe.com/api/events/types.md) que vous souhaitez envoyer à un endpoint webhook. 6. Sélectionnez **Continuer**, puis **endpoint de webhook** comme type de destination. 7. Cliquez sur **Continuer**, puis indiquez l’**URL de l’endpoint** et, éventuellement, une description du webhook. 8. Sur la page des paramètres du webhook, un secret de signature commençant par `whsec_` apparaît. Cliquez sur **Révéler la clé secrète** et copiez la valeur à utiliser lorsque vous [créez un gestionnaire](https://docs.stripe.com/webhooks.md#webhook-endpoint-def). > [Workbench](https://docs.stripe.com/workbench.md) remplace le [Dashboard des développeurs](https://docs.stripe.com/development/dashboard.md) existant. Vous pouvez toujours [créer un endpoint de webhook](https://docs.stripe.com/development/dashboard/webhooks.md) dans le Dashboard des développeurs, mais nous vous recommandons d’utiliser Workbench. #### API Utilisez l’endpoint [/v2/core/event_destinations](https://docs.stripe.com/api/v2/event-destinations.md) pour enregistrer un nouvel endpoint. #### Événements instantanés Pour écouter les [snapshot events](https://docs.stripe.com/api/events/types.md) provenant de votre propre compte, définissez la valeur de [event_payload](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-event_payload) sur `snapshot` et la valeur de [enabled_events](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-enabled_events) sur les types d’événements que vous souhaitez envoyer à l’endpoint webhook : ```curl curl -X POST https://api.stripe.com/v2/core/event_destinations \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-08-26.preview" \ --json '{ "name": "My event destination", "type": "webhook_endpoint", "events_from": [ "@self" ], "event_payload": "snapshot", "enabled_events": [ "payment_intent.succeeded", "payment_intent.payment_failed" ], "webhook_endpoint": { "url": "https://mycompanysite.com/webhook" }, "include": [ "webhook_endpoint.signing_secret" ] }' ``` La sortie contient une valeur `webhook_endpoint.signing_secret` qui commence par `whsec_`. Copiez cette valeur pour l’utiliser lorsque vous [créez un gestionnaire](https://docs.stripe.com/webhooks.md#webhook-endpoint-def). #### Événements légers Si vous utilisez des [événements légers](https://docs.stripe.com/api/v2/core/events/event-types.md), vous devrez inscrire un endpoint de webhook distinct. Apprenez-en plus sur [les différences entre les événements légers et de type snapshot](https://docs.stripe.com/event-destinations.md#events-overview). Pour écouter les [événements légers](https://docs.stripe.com/api/v2/core/events/event-types.md) depuis votre propre compte, définissez la valeur [event_payload](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-event_payload) sur `thin` et la valeur [enabled_events](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-enabled_events) sur les types d’événements que vous souhaitez envoyer à l’endpoint de webhook : ```curl curl -X POST https://api.stripe.com/v2/core/event_destinations \ -H "Authorization: Bearer <>" \ -H "Stripe-Version: 2026-08-26.preview" \ --json '{ "name": "My event destination", "type": "webhook_endpoint", "events_from": [ "@self" ], "event_payload": "thin", "enabled_events": [ "v1.billing.meter.error_report_triggered" ], "webhook_endpoint": { "url": "https://mycompanysite.com/webhook" }, "include": [ "webhook_endpoint.signing_secret" ] }' ``` La sortie contient une valeur `webhook_endpoint.signing_secret` qui commence par `whsec_`. Copiez cette valeur pour l’utiliser lorsque vous [créez un gestionnaire](https://docs.stripe.com/webhooks.md#webhook-endpoint-def). ### Effectuez des tests localement sans URL enregistrée Si vous ne disposez pas d’une URL HTTPS accessible publiquement enregistrée, vous pouvez tester les webhooks localement en utilisant la CLI Stripe pour [transférer les événements vers votre endpoint local](https://docs.stripe.com/cli/use-cli#forward-events-to-your-local-webhook-endpoint) : 1. Si vous ne l’avez pas déjà fait, [installez le Stripe CLI](https://docs.stripe.com/cli/install) sur votre machine. 2. Connectez-vous à votre compte Stripe et configurez le CLI en exécutant `stripe login` dans la ligne de commande. 3. Autorisez votre hôte local à recevoir un événement simulé en exécutant [stripe listen](https://docs.stripe.com/cli/listen), selon la portée et le type d’événement : #### Transférer des événements instantanés Utilisez la commande suivante pour transférer les [snapshot events](https://docs.stripe.com/event-destinations.md#events-overview) de votre compte vers votre listener local. ```bash stripe listen --forward-to localhost:4242/webhook ``` #### Transférer des événements légers Utilisez la commande suivante pour transférer les [événements légers](https://docs.stripe.com/event-destinations.md#events-overview) de votre compte vers votre listener local. ```bash stripe listen --forward-thin-to localhost:4242/webhook --thin-events "*" ``` Cette commande suppose que vous disposez d’un site localhost sur le port 4242 avec un endpoint `POST /webhook`, que vous pouvez configurer lorsque vous [créez un gestionnaire](https://docs.stripe.com/webhooks.md#webhook-endpoint-def). 4. La commande `stripe listen` affiche le `{{WEBHOOK_SIGNING_SECRET}}`. Copiez cette valeur pour l’utiliser lorsque vous [créez un gestionnaire](https://docs.stripe.com/webhooks.md#webhook-endpoint-def). ```output Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit) ``` > Pour utiliser l’argument `--forward-to` avec `stripe listen`, vous devez exécuter la commande avec [Stripe CLI](https://docs.stripe.com/cli.md) dans un terminal. Cette commande ne peut pas être exécutée dans le [Workbench Shell](https://docs.stripe.com/workbench/shell.md), car celui-ci ne prend pas en charge l’argument `--forward-to`. ## Créer un gestionnaire Configurez une fonction endpoint HTTP ou HTTPS pouvant accepter des requêtes de webhook avec une méthode POST. Si votre fonction endpoint est toujours en développement sur votre machine locale, elle peut utiliser HTTP. Une fois publique, elle devra utiliser HTTPS. Utilisez la documentation de l’API Stripe pour identifier les [objets d’événements légers](https://docs.stripe.com/api/v2/core/events/event-types.md) ou d’[événements instantanés](https://docs.stripe.com/api/events/types.md) que votre gestionnaire de webhooks doit traiter. Configurez votre fonction endpoint pour qu’elle : - Gère les requêtes POST contenant un payload JSON avec les informations relatives à l’événement. - Vérifie que la requête webhook a bien été générée par Stripe à l’aide du payload JSON, de l’en-tête `Stripe-Signature` et de la clé secrète de signature `whsec_` obtenue à l’étape précédente. Si la vérification échoue, une erreur est générée. - Retourne rapidement un code de statut réussi (`2xx`) avant toute logique complexe susceptible de provoquer un délai d’expiration. Par exemple, vous devez retourner une réponse `200` avant de mettre à jour une facture client comme étant payée dans votre système comptable. > #### Ne modifiez pas le corps brut de la requête > > Stripe a besoin du contenu brut de la requête pour procéder à la vérification de la signature. Si vous utilisez un framework, assurez-vous qu’il ne manipule pas le contenu brut, auquel cas cela entraînerait automatiquement l’échec de la vérification. > > Découvrez comment [résoudre les erreurs de vérification de signature](https://docs.stripe.com/webhooks/signature.md). #### Exemple de endpoint Cet extrait de code est une fonction de webhook configurée pour vérifier les événements reçus d’un compte Stripe, gérer les événements et renvoyer une réponse `200`. Référencez le gestionnaire d’événements [instantanés](https://docs.stripe.com/event-destinations.md#events-overview) lorsque vous utilisez des ressources d’API v1, et référencez le gestionnaire d’événements [légers](https://docs.stripe.com/event-destinations.md#events-overview) lorsque vous utilisez des ressources d’API v2. #### Gestionnaire d'événements instantanés Lorsque vous créez un gestionnaire d’événements instantanés, utilisez la définition d’objet d’API au moment de l’événement pour votre logique en accédant aux champs `data.object` de l’événement. Vous pouvez également récupérer la ressource d’API à partir de l’API Stripe pour accéder à la définition d’objet la plus récente et à jour. #### Ruby ```ruby require 'json' require 'stripe' client = Stripe::StripeClient.new(ENV.fetch('STRIPE_API_KEY')) # Replace this endpoint secret with your unique endpoint secret key # If you're testing with the CLI, run 'stripe listen' to find the secret key # If you defined your endpoint using the API or the Dashboard, check your webhook settings for your endpoint secret: https://dashboard.stripe.com/webhooks endpoint_secret = 'whsec_...'; # Using Sinatra post '/webhook' do payload = request.body.read event = nil begin event = Stripe::Event.construct_from( JSON.parse(payload, symbolize_names: true) ) rescue JSON::ParserError => e # Invalid payload status 400 return end # Check that you have configured webhook signing if endpoint_secret # Retrieve the event by verifying the signature using the raw body and the endpoint secret signature = request.env['HTTP_STRIPE_SIGNATURE']; begin event = Stripe::Webhook.construct_event( payload, signature, endpoint_secret ) rescue Stripe::SignatureVerificationError => e puts "⚠️ Webhook signature verification failed. #{e.message}" status 400 end end # Handle the event case event.type when 'payment_intent.succeeded' payment_intent = event.data.object # contains a Stripe::PaymentIntent # Then define and call a method to handle the successful payment intent. # handle_payment_intent_succeeded(payment_intent) when 'payment_method.attached' payment_method = event.data.object # contains a Stripe::PaymentMethod # Then define and call a method to handle the successful attachment of a PaymentMethod. # handle_payment_method_attached(payment_method) # ... handle other event types else puts "Unhandled event type: #{event.type}" end status 200 end ``` #### Gestionnaire d’événements légers (Clover+) Lorsque vous créez un gestionnaire d’événements dynamiques, utilisez la méthode `fetchRelatedObject()` pour récupérer la dernière version de l’objet associé à l’événement. Les événements peuvent contenir des [données supplémentaires](https://docs.stripe.com/event-destinations.md#fetch-data) que vous ne pouvez récupérer que via la méthode d’instance `.fetchEvent()` sur`EventNotification`. La forme exacte de ces données dépend du `type` de l’événement. Les types d’événements doivent être disponibles au moment de la publication pour générer des classes dans cette version du SDK. Pour gérer les événements pour lesquels le SDK n’a pas de classes, utilisez la classe `UnknownEventNotification`. #### Python ```python import os from stripe import StripeClient from stripe.events import UnknownEventNotification from flask import Flask, request, jsonify app = Flask(__name__) api_key = os.environ.get("STRIPE_API_KEY", "") webhook_secret = os.environ.get("WEBHOOK_SECRET", "") client = StripeClient(api_key) @app.route("/webhook", methods=["POST"]) def webhook(): webhook_body = request.data sig_header = request.headers.get("Stripe-Signature") try: event_notif = client.parse_event_notification( webhook_body, sig_header, webhook_secret ) # type checkers will narrow the type based on the `type` property if event_notif.type == "v1.billing.meter.error_report_triggered": # in this block, event_notification is typed as # a V1BillingMeterErrorReportTriggeredEventNotification # there's basic info about the related object in the notification print(f"Meter w/ id {event_notif.related_object.id} had a problem") # or you can fetch the full object form the API for more details meter = event_notif.fetch_related_object() print( f"Meter {meter.display_name} ({meter.id}) had a problem" ) # And you can always fetch the full event: event = event_notif.fetch_event() print(f"More info: {event.data.developer_message_summary}") elif event_notif.type == "v1.billing.meter.no_meter_found": # in this block, event_notification is typed as # a V1BillingMeterNoMeterFoundEventNotification # that class doesn't define `fetch_related_object` because the event # has no related object. # so this line would correctly give a type error: # meter = event_notif.fetch_related_object() # but fetching the event always works: event = event_notif.fetch_event() print( f"Err! No meter found: {event.data.developer_message_summary}" ) # Events that were introduced after this SDK version release are # represented as `UnknownEventNotification`s. # They're valid, the SDK just doesn't have corresponding classes for them. # You must match on the "type" property instead. elif isinstance(event_notif, UnknownEventNotification): # these lines are optional, but will give you more accurate typing in this block from typing import cast event_notif = cast(UnknownEventNotification, event_notif) # continue matching on the type property # from this point on, the `related_object` property _may_ be None # (depending on the event type) if event_notif.type == "some.new.event": # if this event type has a related object, you can fetch it obj = event_notif.fetch_related_object() # otherwise, `obj` will just be `None` print(f"Related object: {obj}") # you can still fetch the full event, but it will be untyped event = event_notif.fetch_event() print(f"New event: {event.data}") # type: ignore return jsonify(success=True), 200 except Exception as e: return jsonify(error=str(e)), 400 ``` ## Tester votre gestionnaire Avant de mettre en production votre fonction d’endpoint webhook, nous vous recommandons de tester votre intégration en déclenchant des événements dans un environnement de test ou en envoyant des événements de test avec le [Stripe CLI](https://docs.stripe.com/cli.md). ### 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](https://docs.stripe.com/stripe-vscode.md). #### Déclencher un événement instantané Vous pouvez utiliser la commande suivante dans [Stripe Shell](https://docs.stripe.com/workbench/shell.md) ou la [CLI Stripe](https://docs.stripe.com/cli.md). Cet exemple déclenche un événement `payment_intent.succeeded` : ```bash stripe trigger payment_intent.succeeded Running fixture for: payment_intent Trigger succeeded! Check dashboard for event details. ``` #### Déclencher un événement léger Vous pouvez utiliser la commande suivante dans la [CLI Stripe](https://docs.stripe.com/cli.md). Cet exemple déclenche l’événement `v1.billing.meter.error_report_triggered` : ```bash stripe trigger v1.billing.meter.error_report_triggered Setting up fixture for: list_billing_meters Running fixture for: list_billing_meters Setting up fixture for: billing_meter Running fixture for: billing_meter Setting up fixture for: list_billing_meters_after_creation Running fixture for: list_billing_meters_after_creation Setting up fixture for: billing_meter_event_session Running fixture for: billing_meter_event_session Setting up fixture for: create_billing_meter_event_stream Running fixture for: create_billing_meter_event_stream Trigger succeeded! Check dashboard for event details. ``` ## Optional: Créez une destination d’événements pour Connect Lorsque vous [créez une destination d’événements](https://docs.stripe.com/webhooks.md#create-webhook-endpoint) en tant que plateforme Connect, vous choisissez la portée qu’elle écoute : #### Dashboard - **Votre compte** : événements provenant de ressources de votre compte. - **Comptes connectés** : événements de ressources appartenant à vos comptes connectés. #### API - [events_from=[“@self”]](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-events_from) : événements provenant de ressources de votre compte. - [events_from=[“@accounts”]](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-events_from) : événements de ressources appartenant à vos comptes connectés. Enregistrez une destination d’événements pour les **Comptes connectés** afin de recevoir des événements pour les ressources qui appartiennent à vos comptes connectés. Par exemple, les [paiements directs](https://docs.stripe.com/connect/direct-charges.md), les clients et les moyens de paiement des comptes connectés, les échecs de virement et les mises à jour du cycle de vie des comptes connectés de type snapshot héritées, telles que l’onboarding, la vérification, les modifications de compte externe et les déconnexions de compte. Pour Accounts v2, ce périmètre reçoit uniquement les événements de type snapshot pour les objets Account représentant vos comptes connectés. En fonction de votre intégration Connect, vous devrez peut-être également enregistrer une destination d’événements pour **Votre compte**. Cela peut être nécessaire pour : - Traiter les événements relatifs aux ressources de votre compte de plateforme, notamment les clients de la plateforme, les charges appartenant à la plateforme, les[paiements indirects](https://docs.stripe.com/connect/destination-charges.md) et les [paiements et transferts distincts](https://docs.stripe.com/connect/separate-charges-and-transfers.md). - Traiter des événements légers liés aux objets Accounts v2 représentant les comptes connectés. Pour en savoir plus, consultez [Webhooks Connect](https://docs.stripe.com/connect/webhooks.md?accounts-namespace=v2). ### Testez Connect localement sans URL enregistrée #### Événements instantanés Utilisez la commande suivante pour transférer les [événements de type snapshot](https://docs.stripe.com/event-destinations.md#events-overview) des comptes connectés vers votre écouteur local. ```bash stripe listen --forward-connect-to localhost:4242/webhook ``` #### Événements légers Utilisez la commande suivante pour transférer les [événements légers](https://docs.stripe.com/event-destinations.md#events-overview) des comptes connectés vers votre écouteur local. ```bash stripe listen --forward-thin-connect-to localhost:4242/webhook --thin-events "*" ``` ## Optional: Créez une destination d’événements pour Organizations Lorsque vous [créez une destination d’événements](https://docs.stripe.com/webhooks.md#create-webhook-endpoint) en tant qu’organisation, vous choisissez la portée qu’elle écoute : #### Dashboard - **Comptes au sein de votre organisation** : événements provenant de ressources des comptes de votre organisation. - **Comptes connectés** : événements provenant de ressources au sein des comptes connectés de votre organisation. #### API - [events_from=[« @organization_members »]](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-events_from) : événements provenant de ressources au sein des comptes de votre organisation. - [events_from=[« @organization_members/@accounts »]](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-events_from) : événements provenant de ressources au sein des comptes connectés de votre organisation. ### Comportements de type d’événement non pris en charge pour les destinations d’événements d’organisation Stripe envoie la plupart des types d’événements de manière asynchrone, mais attend une réponse pour certains types d’événements. Dans ces cas, Stripe se comporte différemment selon que la destination répond ou non. Si votre destination d’événement reçoit des événements [d’organisation](https://docs.stripe.com/get-started/account/orgs.md), ceux qui nécessitent une réponse présentent les limitations suivantes : - Vous ne pouvez pas vous abonner à `issuing_authorization.request` pour les destinations d’organisation. Configurez plutôt un [endpoint de webhook](https://docs.stripe.com/webhooks.md#example-endpoint) sur un compte Stripe au sein de l’organisation pour vous abonner à ce type d’événement. Utilisez `issuing_authorization.request` pour autoriser les demandes d’achat en temps réel. - Les destinations de l’organisation qui reçoivent `checkout_sessions.completed` ne peuvent pas [gérer le comportement de redirection](https://docs.stripe.com/checkout/fulfillment.md#redirect-hosted-checkout) lorsque vous intégrez [Checkout](https://docs.stripe.com/payments/checkout.md) directement dans votre site internet ou redirigez les clients vers une page de paiement hébergée par Stripe. Pour influencer le comportement de redirection de Checkout, traitez ce type d’événement avec un [webhook endpoint](https://docs.stripe.com/webhooks.md#example-endpoint) configuré dans un compte Stripe au sein de l’organisation. - Les destinations d’organisation qui ne répondent pas avec succès à un événement `invoice.created` ne peuvent pas influencer la [finalisation automatique des factures lorsque le recouvrement automatique est activé](https://docs.stripe.com/billing/subscriptions/webhooks.md#understand). Vous devez traiter ce type d’événement via un [endpoint webhook](https://docs.stripe.com/webhooks.md#example-endpoint) configuré dans un compte Stripe au sein de l’organisation afin de déclencher la finalisation automatique des factures. #### Utilisant `context` #### Événements instantanés Cet extrait de code est une fonction webhook configurée pour vérifier les événements reçus, détecter le compte d’origine le cas échéant, gérer l’événement et renvoyer une réponse `200`. #### Ruby ```ruby require 'json' client = Stripe::StripeClient.new('sk_...') # Using Sinatra post '/webhook' do payload = request.body.read event = nil begin event = Stripe::Event.construct_from( JSON.parse(payload, symbolize_names: true) ) rescue JSON::ParserError => e # Invalid payload status 400 return end # Extract the context context = event.context # Define your API key variables (ideally loaded securely) ACCOUNT_123_API_KEY = "sk_test_123" ACCOUNT_456_API_KEY = "sk_test_456" account_api_keys = { "account_123" => ACCOUNT_123_API_KEY, "account_456" => ACCOUNT_456_API_KEY } api_key = account_api_keys[context] if api_key.nil? puts "No API key found for context: #{context}" status 400 return end # Handle the event case event.type when 'customer.created' customer = event.data.object begin latest_customer = client.v1.customers.retrieve(customer.id, {api_key: api_key}) handle_customer_created(latest_customer, context) rescue => e puts "Error retrieving customer: #{e.message}" status 500 return end when 'payment_method.attached' payment_method = event.data.object begin latest_payment_method = client.v1.payment_methods.retrieve(payment_method.id, {api_key: api_key}) handle_payment_method_attached(latest_payment_method, context) rescue => e puts "Error retrieving payment method: #{e.message}" status 500 return end else puts "Unhandled event type: #{event.type}" end status 200 end ``` #### Gestionnaire d’événements légers (Clover+) Utilisez la propriété `context` de l’`EventNotification` pour identifier le compte pour les événements au sein de votre [organisation](https://docs.stripe.com/get-started/account/orgs.md). Vous devez définir manuellement l[’en-tête Stripe-Context](https://docs.stripe.com/context.md) pour tous les appels à l’API, sauf pour `.fetchRelatedObject()` et `.fetchEvent()`, qui le font automatiquement pour vous. #### Python ```python org_api_key = os.environ.get("STRIPE_API_KEY") webhook_secret = os.environ.get("WEBHOOK_SECRET") client = StripeClient(org_api_key) # inside your webhook handler event_notification = client.parse_event_notification(payload, sig_header, webhook_secret) # uses `context` automatically event_notification.fetch_event() # pass context manually for other API requests client.v1.invoices.list(stripe_context=event_notification.context) ``` ## Déboguer des intégrations de webhooks Plusieurs types de problèmes peuvent survenir lors de la remise d’événements à votre endpoint de webhook : - Il est possible que Stripe ne parvienne pas à remettre un événement à votre endpoint de webhook. - Votre endpoint de webhook comporte peut-être une erreur SSL. - Votre connectivité réseau est intermittente. - Votre endpoint de webhook ne reçoit pas les événements attendus. ### Afficher les événements remis Pour consulter les livraisons d’événements, ouvrez [Workbench](https://docs.stripe.com/workbench.md), sélectionnez le point de terminaison du webhook dans **Webhooks**, puis ouvrez l’onglet **Livraisons d’événements**. L’onglet **Événement** affiche la liste des événements ainsi que leur statut (`Delivered`, `Pending`, ou `Failed`). Cliquez sur un événement pour voir les métadonnées, notamment le code de statut HTTP de la tentative de livraison et l’heure des prochaines livraisons en attente. Vous pouvez également utiliser la [CLI Stripe](https://docs.stripe.com/cli.md) pour [écouter les événements](https://docs.stripe.com/webhooks.md#test-webhook) directement dans votre terminal. ### Corriger les codes d’état HTTP Quand un événement affiche un code d’état de `200`, cela indique qu’il a bien été remis au endpoint de webhook. Vous pouvez aussi recevoir un code d’état autre que `200`. La liste ci-après détaille les codes d’état fréquents pour le protocole HTTPS, ainsi que les solutions préconisées. | État des webhooks en attente | Description | Rectifier | | --- | --- | --- | | ERR (connexion impossible) | Nous ne parvenons pas à établir une connexion avec le serveur de destination. | Assurez-vous que votre domaine d’hébergement est accessible publiquement sur internet. | | (`302`) ERR (ou autre état `3xx`) | Le serveur de destination a tenté de rediriger la requête vers un autre emplacement. Nous considérons les réponses de redirection aux requêtes de webhook comme des échecs. | Définissez la destination de votre endpoint de webhook vers l’URL déterminée par la redirection. | | ERR (`400`) (ou autre état `4xx`) | Le serveur de destination ne parvient pas à traiter ou rejette la requête. Cela peut se produire lorsque le serveur détecte une erreur (`400`), que l’URL de destination présente des restrictions d’accès (`401`, `403`, `405`) ou que l’URL de destination n’existe pas (`404`). | Assurez-vous que votre endpoint est accessible publiquement sur Internet et qu’il accepte la méthode HTTP POST. | | (`500`) ERR (ou autre état `5xx`) | Le serveur de destination a rencontré une erreur lors du traitement de la requête. | Vérifiez les logs de votre application pour comprendre pourquoi vous recevez une erreur `500`. | | ERR (erreur TLS) | Nous ne sommes pas parvenus à établir une connexion sécurisée avec le serveur de destination. Ces erreurs sont généralement causées par un problème avec le certificat SSL/TLS ou un certificat intermédiaire dans la chaîne de certificats du serveur de destination. Stripe exige *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol) version `v1.2` ou supérieure. | Pour identifier d’éventuels problèmes pouvant engendrer cette erreur, effectuez un [test du serveur SSL](https://www.ssllabs.com/ssltest/). | | ERR (expiré) | Le serveur de destination a mis trop de temps à répondre à la requête de webhook. | Veillez à reporter la logique complexe et à renvoyer immédiatement une réponse positive dans votre code de gestion des webhooks. | ## 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 à votre endpoint de webhook. ### 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](https://docs.stripe.com/cli/events/resend), exécutez la commande `stripe events resend --webhook-endpoint=`. Cette relance fonctionne jusqu’à 30 jours après la création de l’événement. Le renvoi manuel d’un événement dont la livraison à un endpoint de webhook a précédemment échoué n’annule pas le [comportement de nouvelle tentative automatique](https://docs.stripe.com/webhooks.md#automatic-retries) de Stripe, même si cela occasionne un code d’état `2xx`.Découvrez comment [traiter les événements webhook dont la livraison a échoué](https://docs.stripe.com/webhooks/process-undelivered-events.md) pour éviter toute nouvelle tentative. ### 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 vos événements ne dépend pas de la réception d’événements dans un ordre précis. Les événements de type snapshot enregistrent `created` en secondes, des événements distincts peuvent donc partager un même horodatage. N’utilisez pas `created` pour déterminer l’ordre des événements ou pour savoir si vous avez déjà traité un événement. Suivez plutôt les [ID d’événement](https://docs.stripe.com/api/events/object.md#event_object-id) pour identifier les envois en double. Vous pouvez également utiliser l’API pour récupérer tout objet manquant. 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](https://docs.stripe.com/api/events.md), 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](https://docs.stripe.com/api.md#versioning), l’objet [Event](https://docs.stripe.com/api/events.md) 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](https://docs.stripe.com/api/events.md) 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](https://docs.stripe.com/api/events.md) existants. La récupération d’un ancien [Event](https://docs.stripe.com/api/events.md) 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](https://docs.stripe.com/api/events.md) envoyé à la destination est structuré en fonction de la version spécifiée pour la destination de l’événement. ## Bonnes pratiques pour l’utilisation des webhooks Passez en revue ces bonnes pratiques pour vous assurer que vos webhooks restent sécurisés et fonctionnent bien avec votre intégration. ### Gérer les événements en double Les endpoints de webhook peuvent parfois recevoir plusieurs fois le même événement. Vous pouvez vous prémunir contre ce phénomène en enregistrant l’[ID des événements](https://docs.stripe.com/api/events/object.md#event_object-id) que vous avez traités, puis ignorer les événements déjà enregistrés. Dans certains cas, deux objets Event distincts sont générés et envoyés. Pour identifier ces doublons, utilisez l’ID de l’objet dans `data.object` ainsi que le type d’événement (`event.type`). ### Écouter uniquement les types d’événements requis par votre intégration Configurez vos endpoints de webhook de sorte à ne recevoir que les types d’événements requis par votre intégration. L’écoute d’événements supplémentaires (ou de tous les événements) alourdit inutilement la charge de votre serveur, c’est pourquoi nous vous déconseillons cette pratique. Vous pouvez [modifier les événements](https://docs.stripe.com/api/webhook_endpoints/update.md#update_webhook_endpoint-enabled_events) qu’un endpoint de webhook reçoit dans le Dashboard ou à l’aide de l’API. ### Gérer les événements de manière asynchrone Configurez votre gestionnaire de façon à ce qu’il traite les événements entrants avec une file d’attente asynchrone. Vous pouvez rencontrer des problèmes d’évolutivité si vous choisissez de traiter les événements de manière synchrone. Tout pic important d’envoi de webhooks (par exemple, au début du mois, lorsque tous les abonnements sont renouvelés) peut submerger vos hôtes d’endpoint. Les files d’attente asynchrones vous permettent de traiter les événements simultanés à une vitesse que votre système peut prendre en charge. ### Exempter la route des webhooks de la protection CSRF Si vous utilisez Rails, Django ou une autre infrastructure Web, il est possible que votre site vérifie automatiquement que chaque requête POST contient un *token CSRF*. Il s’agit d’une fonctionnalité de sécurité importante qui vous protège, vous et vos utilisateurs, contre les tentatives de [falsification de requêtes intersites](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_\(CSRF\)). Cependant, cette mesure de sécurité peut également empêcher votre site de traiter des événements légitimes. Dans ce cas, vous devrez peut-être retirer la protection CSRF du chemin des webhooks. #### Rails ```ruby class StripeController < ApplicationController # If your controller accepts requests other than Stripe webhooks, # you'll probably want to use `protect_from_forgery` to add CSRF # protection for your application. But don't forget to exempt # your webhook route! protect_from_forgery except: :webhook def webhook # Process webhook data in `params` end end ``` ### Recevoir des événements sur un serveur HTTPS Si vous utilisez une URL HTTPS pour votre endpoint de webhook (obligatoire en mode production), Stripe vérifie que la connexion à votre serveur est sécurisée avant d’envoyer les données de votre webhook. Pour que ce processus fonctionne, votre serveur doit être configuré de sorte à prendre en charge le protocole HTTPS et disposer d’un certificat valide. Les webhooks de Stripe prennent uniquement en charge les versions de *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol) v1.2 et v1.3. ### Invalider régulièrement les clés secrètes de signature des endpoints La clé secrète utilisée pour vérifier que les événements proviennent de Stripe peut être modifié dans l’onglet [Webhooks](https://dashboard.stripe.com/webhooks) de Workbench. Pour assurer leur sécurité, nous vous recommandons de faire tourner (modifier) les clés secrètes régulièrement ou lorsque vous soupçonnez qu’une clé secrète a été compromise. Pour invalider une clé secrète : 1. Cliquez sur chaque endpoint dans l’onglet [Webhooks](https://dashboard.stripe.com/webhooks) de Workbench pour lequel vous souhaitez invalider la clé secrète. 2. Accédez au menu déroulant (⋯) et cliquez sur **Invalider la clé secrète**. Vous pouvez choisir de faire expirer immédiatement la clé secrète actuelle ou de retarder son expiration de 24 heures (maximum) pour vous laisser le temps de mettre à jour le code de vérification sur votre serveur. Dans l’intervalle, plusieurs clés secrètes seront actives pour le endpoint concerné. Stripe génère une signature par clé secrète jusqu’à son expiration. ### Vérifiez que les événements sont envoyés depuis Stripe Sans vérification, un attaquant pourrait envoyer de faux événements webhook à votre endpoint afin de déclencher des actions telles que l’exécution de commandes, l’octroi d’un accès à un compte ou la modification d’enregistrements. Vérifiez toujours que les événements webhook proviennent bien de Stripe avant d’agir. Utilisez les deux protections suivantes : - **Autorisation par liste d’IP** : Stripe envoie les événements webhook depuis une liste définie d’[adresses IP](https://docs.stripe.com/ips.md). Configurez votre serveur ou votre pare-feu pour n’accepter les requêtes webhook que depuis ces adresses. - **Vérification de la signature** : Stripe signe chaque événement webhook en incluant une signature dans l’en-tête `Stripe-Signature`. Vérifiez cette signature à l’aide de nos [bibliothèques officielles](https://docs.stripe.com/webhooks.md#verify-signature) ou [étapes de vérification manuelle](https://docs.stripe.com/webhooks.md?verify=verify-manually#verify-signature) afin de confirmer que l’événement n’a pas été envoyé ou modifié par un tiers. La section suivante décrit comment vérifier les signatures de webhook : 1. Récupérez la clé secrète de votre endpoint. 2. Vérifiez la signature. #### Récupérer la clé secrète de votre endpoint Utilisez Workbench et accédez à l’onglet [Webhooks](https://dashboard.stripe.com/webhooks) pour afficher tous vos endpoints. Sélectionnez un endpoint pour lequel vous souhaitez obtenir la clé secrète, puis cliquez sur **Cliquez pour révéler**. Stripe génère une clé secrète unique pour chaque endpoint. Si vous utilisez le même endpoint pour les [clés API de test et de production](https://docs.stripe.com/keys.md#test-live-modes), la clé secrète est différente pour chacune d’elles. En outre, si vous utilisez plusieurs endpoints, vous devez obtenir une clé secrète pour chacun de ceux dont vous souhaitez vérifier les signatures. Une fois cette configuration terminée, Stripe commence à signer chaque webhook qu’il envoie à l’endpoint. #### Vérifier la signature #### Vérifier à l'aide de bibliothèques officielles (recommandé) ### Vérifier les signatures de webhook à l’aide de bibliothèques officielles Nous vous recommandons d’utiliser nos bibliothèques officielles pour vérifier les signatures. Pour effectuer la vérification, vous devez fournir la charge utile de l’événement, l’en-tête `Stripe-Signature` et la clé secrète de l’endpoint. Une erreur s’affiche en cas d’échec de la vérification. Si vous obtenez une erreur de vérification de la signature, consultez notre guide de [résolution des problèmes](https://docs.stripe.com/webhooks/signature.md). > Stripe a besoin du contenu brut de la requête pour procéder à la vérification de la signature. Si vous utilisez un framework, assurez-vous qu’il ne manipule pas le contenu brut, auquel cas cela entraînerait automatiquement l’échec de la vérification. #### Ruby ```ruby # Don't put any keys in code. See https://docs.stripe.com/keys-best-practices. # Find your keys at https://dashboard.stripe.com/apikeys. client = Stripe::StripeClient.new('<>') require 'stripe' require 'sinatra' # If you are testing your webhook locally with the Stripe CLI you # can find the endpoint's secret by running `stripe listen` # Otherwise, find your endpoint's secret in your webhook settings in # the Developer Dashboard endpoint_secret = 'whsec_...' # Using the Sinatra framework set :port, 4242 post '/my/webhook/url' do payload = request.body.read sig_header = request.env['HTTP_STRIPE_SIGNATURE'] event = nil begin event = Stripe::Webhook.construct_event( payload, sig_header, endpoint_secret ) rescue JSON::ParserError => e # Invalid payload puts "Error parsing payload: #{e.message}" status 400 return rescue Stripe::SignatureVerificationError => e # Invalid signature puts "Error verifying webhook signature: #{e.message}" status 400 return end # Handle the event case event.type when 'payment_intent.succeeded' payment_intent = event.data.object # contains a Stripe::PaymentIntent puts 'PaymentIntent was successful!' when 'payment_method.attached' payment_method = event.data.object # contains a Stripe::PaymentMethod puts 'PaymentMethod was attached to a Customer!' # ... handle other event types else puts "Unhandled event type: #{event.type}" end status 200 end ``` #### Vérifier manuellement ### Vérifier manuellement les signatures de webhook Bien que nous vous recommandions d’utiliser nos bibliothèques officielles pour vérifier les signatures d’événements webhook, cette section vous explique comment créer une solution personnalisée. L’en-tête `Stripe-Signature` inclus dans chaque événement signé contient un horodatage et une ou plusieurs signatures que vous devez vérifier. L’horodatage est précédé d’un préfixe `t=` et chaque signature est précédée d’un préfixe *schéma*. Les schémas commencent par `v`, suivi d’un nombre entier. À l’heure actuelle, le seul schéma de signature valide en mode production est `v1`. Afin de faciliter les tests, Stripe envoie une signature supplémentaire avec un faux schéma `v0` pour les événements de test. ``` Stripe-Signature: t=1492774577, v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd, v0=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39 ``` > Nous avons ajouté des nouvelles lignes pour plus de clarté, mais un véritable en-tête `Stripe-Signature` tient sur une seule ligne. Stripe génère des signatures à l’aide d’un code d’authentification de message basé sur le hachage ([HMAC](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code)) avec [SHA-256](https://en.wikipedia.org/wiki/SHA-2). Pour éviter les [attaques par repli](https://en.wikipedia.org/wiki/Downgrade_attack), ignorez tous les schémas qui ne sont pas `v1`. Vous pouvez avoir plusieurs signatures avec la même paire schéma-clé secrète lorsque vous [invalidez la clé secrète d’un endpoint](https://docs.stripe.com/webhooks.md#roll-endpoint-secrets) et que vous gardez la clé secrète précédente active jusqu’à 24 heures. Pendant cette période, votre endpoint possède plusieurs clés secrètes actives et Stripe génère une signature pour chacune d’entre elles. Pour créer une solution manuelle de vérification des signatures, vous devez suivre les étapes suivantes : #### Étape 1 : Extraire l’horodatage et les signatures de l’en-tête Fractionnez l’en-tête en utilisant le caractère `,` comme séparateur pour obtenir une liste d’éléments. Fractionnez ensuite chaque élément en utilisant le caractère `=` comme séparateur pour obtenir une paire préfixe-valeur. La valeur du préfixe `t` correspond à l’horodatage, et `v1` correspond à la signature (ou aux signatures). Vous pouvez ignorer tous les autres éléments. #### Étape 2 : Préparer la chaîne `signed_payload` La chaîne `signed_payload` est créée par concaténation des éléments suivants : - L’horodatage (sous forme de chaîne) - Le caractère `.` - La charge utile JSON réelle (c’est-à-dire le contenu de la requête) #### Étape 3 : Déterminer la signature attendue Calculez un HMAC avec la fonction de hachage SHA256. Utilisez la clé secrète de signature du endpoint comme clé et la chaîne `signed_payload` comme message. #### Étape 4 : Comparer les signatures Comparez la signature (ou les signatures) dans l’en-tête à la signature attendue. Pour une correspondance d’égalité, calculez la différence entre l’horodatage actuel et l’horodatage reçu, puis déterminez si la différence se situe dans les limites de votre tolérance. Pour vous protéger des attaques temporelles, utilisez une comparaison de chaîne de temps constante pour comparer la signature attendue à chacune des signatures reçues. ### Prévention des attaques par rejeu Une [attaque par rejeu](https://en.wikipedia.org/wiki/Replay_attack) se produit lorsqu’un attaquant intercepte une charge utile valide et sa signature, puis les retransmet. Pour limiter ce type d’attaques, Stripe inclut un horodatage dans l’en-tête `Stripe-Signature`. Comme cet horodatage fait partie de la charge utile signée, il est également vérifié par la signature. Un attaquant ne peut donc pas modifier l’horodatage sans invalider la signature. Si la signature est valide mais que l’horodatage est trop ancien, votre application peut refuser la charge utile. Nos bibliothèques ont une tolérance par défaut de 5 minutes entre l’horodatage et l’heure actuelle. Vous pouvez modifier cette tolérance en fournissant un paramètre supplémentaire lors de la vérification des signatures. Utilisez le protocole Network Time Protocol ([NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)) pour vous assurer que l’heure indiquée par l’horloge de votre serveur est correcte et synchronisée avec l’heure des serveurs de Stripe. > N’utilisez pas une valeur de tolérance de `0`, sous peine de désactiver entièrement le contrôle de récence. Stripe génère l’horodatage et la signature chaque fois que nous envoyons un événement à votre endpoint. Si Stripe tente à nouveau de transmettre un événement (par exemple, si votre endpoint a précédemment répondu avec un code d’état autre que `2xx`), nous générons une nouvelle signature et un nouvel horodatage pour la nouvelle tentative de remise. ### Renvoyer rapidement une réponse 2xx Votre [endpoint](https://docs.stripe.com/webhooks.md#example-endpoint) doit rapidement retourner un code de statut réussi (`2xx`) avant toute logique complexe susceptible de provoquer un délai d’expiration. Par exemple, vous devez retourner une réponse `200` avant de mettre à jour une facture client comme étant payée dans votre système comptable. ## See also - [Envoyer des événements à Amazon EventBridge](https://docs.stripe.com/event-destinations/eventbridge.md) - [Envoyer des événements vers Azure Event Grid](https://docs.stripe.com/event-destinations/eventgrid.md) - [Liste des types d’événements légers](https://docs.stripe.com/api/v2/core/events/event-types.md) - [Liste des types d’événements instantanés](https://docs.stripe.com/api/events/.md) - [Outil interactif pour la création d’endpoints de webhook](https://docs.stripe.com/webhooks/quickstart.md)