Recevez des événements Stripe dans votre point de terminaison de webhook

Lors de la création d’intégrations Stripe, vous voudrez peut-être que vos applications reçoivent des événements au fur et à mesure qu’ils se produisent dans vos comptes Stripe, afin que vos systèmes dorsaux puissent exécuter des actions en conséquence.

Créez une destination d’événement pour recevoir des événements au niveau d’un point de terminaison webhook HTTPS. Après avoir enregistré un point de terminaison webhook, Stripe peut transmettre des données d’événements en temps réel au point de terminaison webhook de votre application lorsque des événements se produisent dans votre compte Stripe. Stripe utilise HTTPS pour envoyer des événements webhook à votre application sous forme de charge utile JSON qui comprend un objet Event.

La réception d’événements de webhook vous permet de réagir à des événements asynchrones, comme la confirmation d’un paiement par l’institution financière d’un client, la contestation d’un paiement par le client ou la réussite d’un paiement récurrent.

Vous pouvez également recevoir des événements sur Amazon EventBridge avec des destinations d’événements.

Premiers pas

Pour commencer à recevoir des événements webhook dans votre application :

1. Créez un gestionnaire de point de terminaison de webhook pour recevoir des requêtes POST de données d’événement.
2. Testez votre gestionnaire de point de terminaison de webhook localement à l’aide de l’interface de ligne de commande Stripe.
3. Créez une destination d’événement pour votre point de terminaison de webhook.
4. Sécurisez votre point de terminaison de webhook.

Vous pouvez enregistrer et créer un point de terminaison pour gérer plusieurs types d’événements simultanément, ou configurer des points de terminaison individuels pour des événements particuliers.

Comportements de types d’événement non pris en charge pour les destinations des événements d’organisation

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 d’organisation offrent une prise en charge limitée des types d’événements nécessitant une réponse :

• Vous ne pouvez pas vous abonner à issuing_authorization.request pour les destinations d’organisation. Configurez plutôt un point de terminaison de webhook dans 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.
• Vous pouvez vous abonner à checkout_sessions.completed pour les destinations d’organisation. 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 à une destination d’organisation n’affectera pas le comportement de redirection. Pour influencer le comportement de redirection de Checkout, traitez ce type d’événement avec un point de terminaison de webhook configuré dans un compte Stripe au sein de l’organisation.
• Vous pouvez vous abonner à invoice.created pour les destinations d’organisation. Toutefois, l’échec de la réponse à cet événement n’a aucune influence sur la finalisation automatique de la facture lors de l’utilisation de l’encaissement automatique. Pour influencer la finalisation automatique des factures par le biais des réponses de point de terminaison de webhook, traitez ce type d’événement avec un point de terminaison de webhook configuré dans un compte Stripe au sein de l’organisation.

http.HandleFunc("/webhook", func(w http.ResponseWriter, req *http.Request) {
    const MaxBodyBytes = int64(65536)
    req.Body = http.MaxBytesReader(w, req.Body, MaxBodyBytes)
    payload, err := ioutil.ReadAll(req.Body)
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error reading request body: %v\n", err)
        w.WriteHeader(http.StatusServiceUnavailable)
        return
    }

    event := stripe.Event{}

    if err := json.Unmarshal(payload, &event); err != nil {
        fmt.Fprintf(os.Stderr, "Failed to parse webhook body json: %v\n", err.Error())
        w.WriteHeader(http.StatusBadRequest)
        return
    }

    // Unmarshal the event data into an appropriate struct depending on its Type
    switch event.Type {
    case "payment_intent.succeeded":
        var paymentIntent stripe.PaymentIntent
        err := json.Unmarshal(event.Data.Raw, &paymentIntent)
        if err != nil {
            fmt.Fprintf(os.Stderr, "Error parsing webhook JSON: %v\n", err)
            w.WriteHeader(http.StatusBadRequest)
            return
        }
        // Then define and call a func to handle the successful payment intent.
        // handlePaymentIntentSucceeded(paymentIntent)
    case "payment_method.attached":
        var paymentMethod stripe.PaymentMethod
        err := json.Unmarshal(event.Data.Raw, &paymentMethod)
        if err != nil {
            fmt.Fprintf(os.Stderr, "Error parsing webhook JSON: %v\n", err)
            w.WriteHeader(http.StatusBadRequest)
            return
        }
        // Then define and call a func to handle the successful attachment of a PaymentMethod.
        // handlePaymentMethodAttached(paymentMethod)
    // ... handle other event types
    default:
        fmt.Fprintf(os.Stderr, "Unhandled event type: %s\n", event.Type)
    }

    w.WriteHeader(http.StatusOK)
})

require 'json'

# 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 = Stripe::Customer.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 = Stripe::PaymentMethod.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

stripe listen --forward-to localhost:4242/webhook

stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \
  --forward-to localhost:4242/webhook

stripe listen --load-from-webhooks-api --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)

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

Enregistrer votre point de terminaison

Après avoir testé la fonction de votre point de terminaison de webhook, utilisez l’API ou l’onglet Webhooks de Workbench pour enregistrer l’URL accessible de votre point de terminaison de webhook afin que Stripe sache où envoyer les événements. Vous pouvez enregistrer jusqu’à 16 points de terminaison de webhook auprès de Stripe. Les points de terminaison de webhook enregistrés doivent être des URL HTTPS accessibles au public.

Format d’URL de webhook

Le format d’URL pour enregistrer un point de terminaison de webhook est le suivant :

https://<your-website>/<your-webhook-endpoint>

Par exemple, si votre domaine est https://mycompanysite.com et que le chemin vers votre point de terminaison de webhook est @app.route('/stripe_webhooks', methods=['POST']), précisez https://mycompanysite.com/stripe_webhooks comme l’URL du point de terminaison.

Créer une destination d’événement pour votre point de terminaison de webhook

Créez une destination d’événement à l’aide de Workbench dans le Dashboard ou par voie programmatique à l’aide de l’API. Vous pouvez inscrire jusqu’à 16 destinations d’événements dans chaque compte Stripe.

Le Dashboard.

L'API

Pour créer un nouveau point de terminaison webhook dans le Dashboard :

1. Ouvrez l’onglet Webhooks dans Workbench.
2. Cliquez sur Créer une destination d’événement.
3. Sélectionnez l’endroit duquel 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’un point de terminaison de webhook d’organisation

Si vous créez un point de terminaison de webhook 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 la version de l’API pour l’objet d’événements que vous souhaitez utiliser.
2. Sélectionnez les types d’événements que vous souhaitez envoyer à un point de terminaison de webhook.
3. Sélectionnez Continuer, puis sélectionnez le point de terminaison webhook comme type de destination.
4. Cliquez sur Continuer, puis indiquez l’URL du point de terminaison et une description facultative du webhook.

Enregistrer un nouveau webhook à l’aide de l’onglet Webhooks

Remarques

Workbench remplace le Dashboard des développeurs existant. Si vous utilisez toujours le Dashboard des développeurs, découvrez comment créer un point de terminaison webhook.

// Set your secret key. Remember to switch to your live secret key in production.
// See your keys here: https://dashboard.stripe.com/apikeys
stripe.Key = 
"sk_test_BQokikJOvBiI2HlWgH4olfQ2"

http.HandleFunc("/webhook", func(w http.ResponseWriter, req *http.Request) {
    const MaxBodyBytes = int64(65536)
    req.Body = http.MaxBytesReader(w, req.Body, MaxBodyBytes)
    payload, err := ioutil.ReadAll(req.Body)
    if err != nil {
        fmt.Fprintf(os.Stderr, "Error reading request body: %v\n", err)
        w.WriteHeader(http.StatusServiceUnavailable)
        return
    }

    // 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
    endpointSecret := "whsec_...";

    // Pass the request body and Stripe-Signature header to ConstructEvent, along
    // with the webhook signing key.
    event, err := webhook.ConstructEvent(payload, req.Header.Get("Stripe-Signature"),
        endpointSecret)

    if err != nil {
        fmt.Fprintf(os.Stderr, "Error verifying webhook signature: %v\n", err)
        w.WriteHeader(http.StatusBadRequest) // Return a 400 error on a bad signature
        return
    }

    // Unmarshal the event data into an appropriate struct depending on its Type
    switch event.Type {
    case "payment_intent.succeeded":
        var paymentIntent stripe.PaymentIntent
        err := json.Unmarshal(event.Data.Raw, &paymentIntent)
        if err != nil {
            fmt.Fprintf(os.Stderr, "Error parsing webhook JSON: %v\n", err)
            w.WriteHeader(http.StatusBadRequest)
            return
        }
        fmt.Println("PaymentIntent was successful!")
    case "payment_method.attached":
        var paymentMethod stripe.PaymentMethod
        err := json.Unmarshal(event.Data.Raw, &paymentMethod)
        if err != nil {
            fmt.Fprintf(os.Stderr, "Error parsing webhook JSON: %v\n", err)
            w.WriteHeader(http.StatusBadRequest)
            return
        }
        fmt.Println("PaymentMethod was attached to a Customer!")
    // ... handle other event types
    default:
        fmt.Fprintf(os.Stderr, "Unhandled event type: %s\n", event.Type)
    }

    w.WriteHeader(http.StatusOK)
})

Déboguer les intégrations de webhooks

Plusieurs types de problèmes peuvent survenir lors de l’envoi d’événements à votre point de terminaison de webhook :

• Il est possible que Stripe ne soit pas en mesure d’envoyer un événement à votre point de terminaison de webhook.
• Votre point de terminaison de webhook peut avoir un problème SSL.
• Votre connexion réseau est intermittente.
• Votre point de terminaison de webhook ne reçoit pas les événements que vous vous attendez à recevoir.

Afficher les envois d’événements

Pour afficher les événements envoyés, sélectionnez le point de terminaison de webhook sous Webhooks, puis sélectionnez l’onglet Événements.

L’onglet Événements fournit une liste des événements et indique s’ils sont Delivered, Pending, ou Failed. Cliquez sur un événement pour afficher les Delivery attempts, qui comprennent le code d’état HTTP des tentatives d’envoi précédentes et l’heure des envois futurs en attente.

Afficher les tentatives d’envoi d’événements dans l’onglet Événements d’un point de terminaison de webhook.

Corriger des codes d’état HTTP

Lorsqu’un événement affiche un code d’état de 200, il indique qu’un envoi a été effectué au point de terminaison de webhook. Vous pourriez également recevoir un code d’état autre que 200. Consultez le tableau ci-dessous pour obtenir une liste des codes d’état HTTP courants et des solutions recommandées.

Comportements d’envoi d’événements

Cette section vous aide à comprendre les différents comportements à attendre concernant la façon dont Stripe envoie les événements à votre point de terminaison de webhook.

Relances automatiques

Stripe tente d’envoyer des événements à votre destination pendant un maximum de trois jours avec un délai exponentiel en mode production. Affichez la date de la prochaine tentative, le cas échéant, dans l’onglet Événements envoyés de votre destination d’événement. Nous tentons de renvoyer les événements créés dans un bac à sable trois fois au cours de quelques heures. Si votre destination a été désactivée ou supprimée lorsque nous effectuons une nouvelle tentative, nous empêcherons toute nouvelle tentative d’envoi de cet événement. Toutefois, si vous désactivez, puis réactivez la destination de l’événement avant que nous puissions réessayer, d’autres tentatives seront toujours possibles.

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

Commande d’événements

Stripe ne garantit pas que les événements sont envoyés 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 existe)

Assurez-vous que la destination de votre événement ne dépend pas de la réception d’événements dans un ordre particulier. Soyez prêt à gérer leur envoi de manière appropriée. Vous pouvez également utiliser l’API pour récupérer tout objet manquant. Par exemple, vous pourrez récupérer les objets relatifs à la facture, le paiement et l’abonnement avec les informations de invoice.paid si vous recevez cet événement en premier.

Contrôle de version 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.

Bonnes pratiques pour l’utilisation des webhooks

Vérifiez les bonnes pratiques suivantes pour vous assurer que vos points de terminaison de webhooks restent sécurisés et fonctionnent correctement au sein de votre intégration.

Gérer les événements en double

Les points de terminaison Webhook peuvent parfois recevoir plusieurs fois le même événement. Vous pouvez vous prémunir contre ce phénomène en enregistrant les ID d’événements que vous avez traités et en ne traitant pas 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 avec event.type.

Écoutez uniquement les types d’événements nécessaires à votre intégration

Configurez vos points de terminaison de webhook de sorte à ne recevoir que les types d’événements nécessaires à 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 ne le recommandons pas.

Vous pouvez modifier les événements qu’un point de terminaison 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 pour traiter 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. Toute augmentation importante des envois de webhooks (par exemple, au début du mois, lorsque tous les abonnements sont renouvelés) pourrait submerger les hôtes de vos points de terminaison.

Les files d’attente asynchrones vous permettent de traiter les événements simultanés à un rythme que votre système peut prendre en charge.

Chemin de webhook exempté de la protection CSRF

Si vous utilisez Rails, Django ou un autre cadre Web, votre site peut vérifier automatiquement que chaque requête POST contient un jeton CSRF token. Cette mesure de sécurité importante vous protège vous et vos utilisateurs des tentatives de falsification de requête intersites. Toutefois, elle peut également empêcher votre site de traiter des événements légitimes. Dans ce cas, vous devrez peut-être exempter le chemin des webhooks de cette protection CSRF.

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 avec un serveur HTTPS

Si vous utilisez une URL HTTPS pour votre point de terminaison de webhook (obligatoire en mode production), Stripe vérifiera 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 de serveur valide. Les webhooks de Stripe prennent en charge uniquement le protocoleTLS, versions v.1.2 et v1.3.

Échangez périodiquement les clés secrètes de signature des points de terminaison

La clé secrète utilisée pour vérifier que les événements proviennent de Stripe est modifiable dans l’onglet Webhooks de Workbench. Pour assurer leur sécurité, nous vous recommandons d’échanger (ou de modifier) les clés secrètes périodiquement, ou lorsque vous soupçonnez que l’une d’entre elles est compromise.

Pour échanger une clé secrète :

1. Cliquez sur chaque point de terminaison dans l’onglet Webhooks de Workbench pour lequel vous souhaitez échanger la clé secrète.
2. Accédez au menu de débordement () et cliquez sur Nouvelle clé secrète. Vous pouvez choisir de faire expirer immédiatement la clé secrète actuelle ou de retarder son expiration jusqu’à 24 heures pour vous donner le temps de mettre à jour le code de vérification sur votre serveur. Pendant ce temps, plusieurs clés secrètes sont actives pour le point de terminaison. Stripe génère une signature par clé secrète jusqu’à expiration.

Vérifier que les événements sont envoyés par Stripe

Stripe envoie les événements de webhooks à partir d’une liste d’adresses IP prédéfinie. Ne faites confiance qu’aux événements prvenant de ces adresses IP.

Vérifiez également les signatures des webhooks pour confirmer que Stripe a bien envoyé les événements reçus. Stripe signe les événements de webhook qu’il envoie à vos points de terminaison en incluant une signature dans l’en-tête Stripe-Signature de chaque événement. Cela vous permet de vérifier que les événements ont bien été envoyés par Stripe et non par un tiers. Vous pouvez vérifier les signatures à l’aide de nos bibliothèques officielles, ou vérifier manuellement à l’aide de votre propre solution.

La section suivante décrit comment vérifier les signatures de webhook :

1. Récupérez la clé secrète de votre point de terminaison.
2. Vérifiez la signature.

Récupération de la clé secrète de votre point de terminaison

Utilisez Workbench et accédez à l’onglet Webhooks pour afficher tous vos points de terminaison. Sélectionnez un point de terminaison pour lequel vous souhaitez obtenir la clé secrète, puis cliquez sur Cliquer pour révéler.

Stripe génère une clé secrète unique pour chaque point de terminaison. Si vous utilisez le même point de terminaison pour les clés API de test et de production, la clé secrète sera différente pour chacun. De plus, si vous utilisez plusieurs points de terminaison, vous devrez obtenir une clé secrète pour chaque point de terminaison dont vous voulez vérifier les signatures. Après cette configuration, Stripe commencera à signer chaque webhook qu’il envoie au point de terminaison.

Prévention des attaques par réinsertion

Une attaque par réinsertion se produit lorsqu’un attaquant intercepte une charge utile valide et sa signature, puis les retransmet. Pour éviter ces attaques, Stripe inclut un horodatage dans l’en-tête Stripe-Signature. Étant donné que cet horodatage fait partie de la charge utile signée, il est également vérifié par la signature, de sorte qu’un attaquant ne peut pas modifier l’horodatage sans invalider la signature. Si la signature est valide, mais que l’horodatage est trop ancien, vous pouvez demander à votre application de rejeter la charge utile.

Nos bibliothèques ont une tolérance par défaut de cinq 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 de synchronisation de réseau (NTP) pour vous assurer que l’horloge de votre serveur est précise et synchronisée avec l’heure des serveurs de Stripe.

Stripe génère l’horodatage et la signature chaque fois que nous envoyons un événement à votre point de terminaison. Si Stripe tente à nouveau d’envoyer un événement (par exemple, si votre point de terminaison a précédemment répondu avec un code d’état autre que 2xx), nous générerons une nouvelle signature et un nouvel horodatage pour la nouvelle tentative d’envoi.

Renvoyer rapidement une réponse 2xx

Votre point de terminaison doit renvoyer rapidement un code d’état réussi (2xx) avant toute logique complexe qui pourrait provoquer une expiration du délai imparti. Par exemple, vous devez renvoyer une réponse 200 avant de mettre à jour la facture d’un client comme étant payée dans votre système de comptabilité.