Recevez des événements Stripe dans votre point de terminaison de webhook
Envoyez des événements à votre compte AWS
Nous lançons un service d’assistance pour recevoir des événements de Stripe sur Amazon EventBridge en version bêta privée. Pour bénéficier d’un accès anticipé, inscrivez-vous sur eventbridge.stripe.dev.
Pourquoi utiliser les webhooks
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.
Pour activer les événements avec webhooks, vous devez enregistrer des points de terminaison pour les webhooks. Une fois que vous les avez enregistrés, Stripe peut transférer des données d’événement en temps réel vers le point de terminaison du webhook de votre application lorsque des événements se produisent dans votre compte Stripe. Stripe utilise HTTPS pour envoyer des événements avec webhooks à votre application en tant que charge utile JSON qui comprend un objet Event.
La réception d’événements avec webhooks est particulièrement utile pour écouter les événements asynchrones comme lorsque l’institution financière d’un client confirme un paiement, lorsqu’un client conteste un paiement, lorsqu’un paiement récurrent est effectué ou les paiement d’abonnement sont encaissés.
Aperçu de l’événement
Stripe génère des données d’événement que nous pouvons vous envoyer pour vous informer de l’activité de votre compte.
Lorsqu’un événement se produit, Stripe génère un nouvel objet Event. Une seule requête à l’API peut entraîner la création de plusieurs événements. Par exemple, si vous créez un nouvel abonnement pour un client, vous recevrez les événements customer.subscription.created
et payment_intent.succeeded
.
En enregistrant des points de terminaison de webhook dans votre compte Stripe, vous activez Stripe dans le but d’envoyer automatiquement des objets Event au point de terminaison de webhook enregistré hébergé par votre application dans le cadre de requêtes POST. Une fois que votre point de terminaison de webhook a reçu l’événement, votre application peut exécuter des actions dans l’application dorsale (par exemple, effectuer des appels aux API de votre fournisseur de services de livraison pour planifier une livraison après que vous ayez reçu un événement payment_intent.succeeded
).
Objet Event
L’objet Event que nous envoyons à votre point de terminaison de webhook fournit un aperçu de l’objet qui a changé. Il peut inclure une propriété previous_attributes
qui indique la modification, le cas échéant.
Consultez la liste complète des types d’événements qui peuvent être envoyés à votre webhook.
Exemple de charge utile d’événement
L’événement suivant montre une mise à jour de l’abonnement à la fin de la période d’essai.
{ "id": "evt_1MqqbKLt4dXK03v5qaIbiNCC", "object": "event", "api_version": "2024-04-10", "created": 1680064028,
Structure de l’objet Event
Passez en revue la structure de l’objet Event pour mieux comprendre les événements et les informations sous-jacentes qu’ils fournissent.
Type d’événement
Vous recevez des événements pour tous les types d’événements que votre point de terminaison de webhook écoute dans votre configuration. Utilisez le type
d’événement reçu pour déterminer le traitement que votre application doit effectuer. Le type de data.object
correspondant à chaque événement type
varie.
Mode production et mode test
Vous pourriez recevoir des demandes d’envoi d’événements en mode production et en mode test à vos points de terminaison. Cela peut se produire si vous utilisez un seul point de terminaison pour le mode production et le mode test ou si vous êtes une plateforme Connect qui effectue des demandes de mode test pour des comptes connectés Standard en mode production. Utilisez l’attribut livemode
pour vérifier si l’objet existe en mode production ou en mode test, et déterminez la façon de gérer l’événement.
Version de l’API
L’attribut api_version
indique la version d’API de l’événement et dicte la structure du data.object inclus. Votre point de terminaison reçoit des événements à l’aide de la version d’API configurée, qui peut différer de la version d’API par défaut de votre compte ou de la version d’API de toutes les demandes liées à l’événement. Cet attribut est déterminé par le point de terminaison de destination, ce qui indique que le même événement peut être envoyé à plusieurs points de terminaison à l’aide de différentes versions d’API. Si vous utilisez nos bibliothèques de clients Java, .NET ou Go, assurez-vous de configurer la version de l’API du point de terminaison pour utiliser la même version d’API épinglée dans le client. Sinon, vous risquez de ne pas pouvoir désérialiser les objets de l’événement.
Lors de la récupération d’objets Event de l’API, vous ne pouvez pas contrôler la version de l’API de la structure data.object
. Au lieu de cela, récupérez cet objet à partir du point de terminaison d’API approprié et utilisez l’en-tête Stripe-Version
pour préciser une version d’API.
Événements de requête à l’API
Lorsqu’un événement est généré à la suite d’une requête à l’API, cette requête est affichée sous la forme request.id
. Si vous utilisez une idempotency_key
lors de la création de la requête, cette dernière sera incluse en tant que request.idempotency_key
. Vérifiez le hachage request
lorsque vous examinez la cause d’un événement.
Objet de données et attributs antérieurs
Pour les événements *.updated
, la charge utile de l’événement comprend data.previous_attributes
qui vous permet d’examiner ce qui a changé à propos de l’objet Stripe. L’attribut previous_ attributes
dans l’exemple de l’événement customer.subscription.updated
ci-dessus indique que, parmi diverses modifications, l’abonnement a une valeur précédente de status: trialing
. Le data.object
indique que l’état est active
, ce qui indique que la période d’essai pour l’abonnement est maintenant terminée.
Envois en attente
Utilisez pending_webhooks
pour déterminer le nombre de points de terminaison configurés pour cet événement qui n’ont pas bien fonctionné face à l’envoi. Lors de l’envoi initial, cette valeur est égale ou supérieure à 1, car votre point de terminaison n’a pas fonctionné correctement. Si vous récupérez cet événement ultérieurement, pending_webhooks
diminue à un minimum de 0 lorsque chaque point de terminaison fonctionne. Ceci est important pour les événements invoice.created
, car les envois échoués peuvent retarder la finalisation de la facture.
Événements dans un compte connecté
Les événements de comptes connectés envoyés à un point de terminaison Connect comprennent account
. Utilisez account
pour suivre le compte connecté auquel l’objet appartient afin de vous assurer que votre plateforme peut traiter les données de l’événement de manière appropriée.
Pourquoi les objets événements sont générés
Ce tableau décrit différents scénarios qui déclenchent la génération d’objets Event.
Source | Déclencheur |
---|---|
Dashboard | Lorsque vous effectuez un appel à l’API en modifiant vos ressources Stripe dans le Dashboard Stripe. |
API | Lorsqu’une action de l’utilisateur dans votre application ou votre site Web entraîne un appel à l’API. |
API | Lorsque vous déclenchez manuellement un événement avec l’interface de ligne de commande Stripe. |
API | Lorsque vous effectuez un appel à l’API directement à l’aide de l’interface de ligne de commande Stripe. |
Démarrer
Pour commencer à recevoir des événements webhook dans votre application, créez et enregistrez un point de terminaison de webhook en suivant les étapes ci-dessous :
- Créez un gestionnaire de point de terminaison de webhook pour recevoir des requêtes POST de données d’événement.
- Testez votre gestionnaire de point de terminaison de webhook localement à l’aide de l’interface de ligne de commande Stripe.
- Enregistrez votre point de terminaison dans Stripe à l’aide du Dashboard ou de l’API.
- 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 différents à la fois, ou configurer des points de terminaison individuels pour des événements particuliers.
Créer un gestionnaire
Configurez une fonction de point de terminaison HTTP ou HTTPS qui peut accepter les requêtes de webhook avec une méthode POST. Si vous développez toujours votre fonction de point de terminaison sur votre appareil local, elle peut utiliser HTTP. Une fois qu’elle est accessible au public, votre fonction de point de terminaison de webhook doit utiliser HTTPS.
Configurez votre fonction de point de terminaison de manière à ce qu’elle :
- Gère les requêtes POST avec une charge utile JSON constituée d’un objet Event.
- Renvoie rapidement un code d’état réussi (
2xx
) avant de renvoyer toute logique complexe qui pourrait provoquer une expiration du délai imparti. Par exemple, vous devez renvoyer une réponse200
avant de mettre à jour la facture d’un client comme étant payée dans votre système comptable.
Remarques
Vous pouvez également créer une fonction de point de terminaison de webhook dans votre langage de programmation à l’aide de notre outil interactif de création de point de terminaison de webhook.
Exemple de point de terminaison
Cet extrait de code est une fonction webhook configurée pour vérifier que le type d’événement a bien été reçu, pour gérer l’événement, puis pour renvoyer une réponse 200.
Testez votre gestionnaire
Avant de mettre en production votre fonction de point de terminaison de webhook, nous vous recommandons de tester l’intégration de votre application. Pour ce faire, vous pouvez configurer un écouteur local pour envoyer des événements à votre appareil local et envoyer des événements de test. Vous devez utiliser l’interface de ligne de commande pour effectuer ces tests.
Transférer des événements à un point de terminaison local
Pour transférer des événements à votre point de terminaison local, exécutez la commande suivante avec l’interface de ligne de commande pour configurer un écouteur local. L’indicateur --forward-to
envoie tous les événements Stripe en mode test à votre point de terminaison de webhook local.
stripe listen --forward-to localhost:4242/stripe_webhooks
Remarques
Vous pouvez également exécuter la commande d’écoute de Stripe sur Stripe Shell pour voir les événements via le terminal de Stripe Shell, bien que vous ne puissiez pas transférer les événements du Shell à votre point de terminaison local.
Les configurations suivantes sont utiles pour vous aider à effectuer des tests avec votre écouteur local :
- Pour désactiver la vérification du certificat HTTPS, utilisez l’indicateur facultatif
--skip-verify
. - Pour transférer uniquement des événements spécifiques, utilisez l’indicateur optionnel
--events
et passez à une liste d’événements séparés par une virgule.
stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \ --forward-to localhost:4242/webhook
- Pour transférer les évènements à votre point de terminaison de webhook local depuis votre point de terminaison de webhook public enregistré dans Stripe, utilisez l’indicateur facultatif
--load-from-webhooks-api
. Celui-ci charge votre point de terminaison enregistré, analyse le chemin et ses évènements enregistrés, et ajoute ensuite le chemin à votre point de terminaison de webhook local dans le chemin--forward-to path
.
stripe listen --load-from-webhooks-api --forward-to localhost:5000
- Pour vérifier les signatures de webhook, utilisez le
{{WEBHOOK_SIGNING_SECRET}}
à partir de la sortie initiale de la commande d’écoute.
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
Déclenchement d’é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 associée en créant manuellement un objet via le Dashboard Stripe. Vous pouvez également utiliser la commande suivante dans Stripe Shell ou l’interface de ligne de commande Stripe.
Cet exemple illustre le déclenchement d’un événement payment_intent.succeeded
:
stripe trigger payment_intent.succeeded Running fixture for: payment_intent Trigger succeeded! Check dashboard for event details.
Remarques
Découvrez comment déclencher des événements avec Stripe pour VS Code.
Enregistrer votre point de terminaison dans Stripe
Après avoir testé votre fonction de point de terminaison de webhook, enregistrez l’URL accessible du point de terminaison de webhook dans la section Webhooks du Dashboard du développeur ou de l’API afin d’indiquer à Stripe où envoyer les événements. Vous pouvez enregistrer jusqu’à 16 points de terminaison de webhook avec Stripe. Les points de terminaison de webhook enregistrés doivent contenir 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.
Ajouter un point de terminaison de webhook
Remarques
Si vous avez activé Workbench dans votre compte, vous devez utiliser Workbench pour enregistrer votre point de terminaison de webhook.
Stripe prend en charge des points de terminaison de deux types : Account et_Connect_. Créez un point de terminaison de type Account, sauf si vous avez créé une application Connect. Effectuez les étapes suivantes pour enregistrer un point de terminaison de webhook dans le Dashboard des développeurs. Vous pouvez enregistrer jusqu’à 16 points de terminaison de webhook dans chaque compte Stripe.
- Rendez-vous à la page Webhooks.
- Cliquez sur Ajouter un point de terminaison.
- Ajoutez l’URL HTTPS de votre point de terminaison de webhook dans l’URL du point de terminaison.
- Si vous avez un compte Stripe Connect, saisissez une description, puis cliquez sur Écouter les événements sur les comptes connectés.
- Sélectionnez les types d’événements que vous recevez actuellement dans votre point de terminaison de webhook local dans Sélectionner des événements.
- Cliquez sur Ajouter un point de terminaison.
Enregistrer un point de terminaison de webhook avec l’API Stripe
Vous pouvez également créer des points de terminaison de webhook par programmation.
Pour recevoir des événements de comptes connectés, utilisez le paramètre connect.
L’exemple suivant illustre la création d’un point de terminaison qui vous informe si le paiement a été effectué ou a échoué.
Sécuriser votre point de terminaison
Nous vous recommandons vivement de sécuriser votre intégration en vous assurant que votre gestionnaire vérifie que toutes les requêtes de webhook sont générées par Stripe. Vous pouvez choisir de vérifier les signatures de webhook à l’aide de nos bibliothèques officielles ou de les vérifier manuellement.
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 événements envoyés
Remarques
Si vous avez activé Workbench dans votre compte, vous devez utiliser Workbench pour gérer les événements envoyés.
Pour afficher les événements envoyés pour un point de terminaison en particulier, sélectionnez le point de terminaison de webhook dans l’onglet Webhooks.
Pour afficher tous les événements qui ont été déclenchés dans votre compte, consultez l’onglet Événements.
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.
État du webhook en attente | Description | Corriger |
---|---|---|
(Connexion impossible) ERR | Nous ne parvenons pas à établir une connexion au serveur de destination. | Assurez-vous que votre domaine hôte est accessible au public 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 du point de terminaison du webhook sur l’URL déterminée par la redirection. |
(400 ) ERR (ou autre état 4xx ) | Le serveur de destination ne peut traiter ou ne traite pas la requête. Cela peut se produire lorsque le serveur détecte une erreur (400 ), lorsque l’adresse URL de destination comporte des restrictions d’accès (401 , 403 ), ou lorsque l’URL de destination n’existe pas (404 ). |
|
(500 ) ERR (ou autre état 5xx ) | Une erreur est survenue sur le serveur de destination lors du traitement de la requête. | Passez en revue les journaux de votre application pour comprendre pourquoi elle renvoie une erreur 500 . |
(erreur TLS) ERR | Nous n’avons pas pu établir une connexion sécurisée au 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. | Effectuez un test de serveur SSL pour détecter les problèmes susceptibles de provoquer cette erreur. |
(Expiré) ERR | Le serveur de destination a mis trop de temps à répondre à la requête de webhook. | Assurez-vous de différer la logique complexe et à renvoyer immédiatement une réponse réussie dans votre code de gestion de webhook. |
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.
Réessayer le comportement
En mode production, Stripe tente d’envoyer un événement donné à vos points de terminaison de webhook pendant un maximum de trois jours, avec un délai d’attente exponentiel. Vous pouvez consulter le moment de la prochaine relance dans la section Événements du Dashboard.
En mode test, Stripe procède à trois relances sur une période de quelques heures. Vous pouvez réessayer manuellement de transmettre des événements individuels à votre point de terminaison de webhook une fois ce délai écoulé à l’aide de la section Événements du Dashboard. Vous pouvez également envoyer une requête pour les événements manqués pour rapprocher les données sur n’importe quelle période.
Les tentatives automatiques se poursuivent, même si vous essayez de transmettre manuellement des événements de webhook individuels à un point de terminaison donné et que la tentative a fonctionné.
Si votre point de terminaison a été désactivé ou supprimé lorsque Stripe effectue une nouvelle tentative, toute relance ultérieure de cet événement sera annulée. Toutefois, si vous désactivez, puis réactivez un point de terminaison de webhook avant que Stripe ne puisse réessayer, des tentatives ultérieures seront toujours possibles.
Désactiver le comportement
En mode test et en mode production, Stripe essaie de vous informer par courriel de l’existence d’un point de terminaison configuré incorrectement lorsque le point de terminaison n’a pas envoyé de code d’état HTTP 2xx
pendant plusieurs jours consécutifs. Ce courriel indique également le moment où le point de terminaison sera désactivé automatiquement.
Contrôle de version de l’API
Lorsque l’événement survient, la version de l’API dans les paramètres de votre compte dicte la version de l’API, puis la structure d’un objet Event
envoyé dans un webhook. Par exemple, si votre compte utilise une ancienne version d’API, comme 2015-02-16, et que vous modifiez la version de l’API à utiliser pour une requête spécifique avec le contrôle de versions, l’objet Event
généré et envoyé à votre point de terminaison est toujours fondé sur la version de l’API 2015-02-16.
Vous ne pouvez pas modifier les objets Event
une fois qu’ils ont été créés. Par exemple, si un paiement est mis à jour, l’événement de paiement d’origine reste inchangé. Cela signifie que 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
. La récupération d’anciens événements en effectuant un appel à /v1/events
à l’aide d’une version récente de l’API n’a pas non plus de conséquence sur la structure des événements reçus.
Vous pouvez définir des points de terminaison de webhook de test à la version de l’API par défaut ou à la version la plus récente. L’objet Event
envoyé à l’URL du webhook est structuré en fonction de la version précisée du point de terminaison. Vous pouvez également créer des points de terminaison par programmation avec un paramètre api_version spécifique.
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)
Votre point de terminaison ne doit pas s’attendre à ce que ces événements soient envoyés dans cet ordre et doit donc gérer leur envoi en conséquence. 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 à l’aide des informations de l’événement invoice.paid
si vous le recevez en premier).
Bonnes pratiques pour l’utilisation des webhooks
Passez en revue les bonnes pratiques suivantes pour vous assurer que vos 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 de webhook peuvent recevoir plusieurs fois un même événement. Vous pouvez vous prémunir contre cette situation en rendant votre traitement des événements idempotent. Pour ce faire, vous pouvez par exemple consigner les événements traités, puis ignorer ceux qui sont déjà consignés.
É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.
Recevoir des événements sur un serveur HTTPS
Si vous utilisez une URL HTTPS pour votre point de terminaison de webhook, 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 URL HTTPS sont obligatoires en mode production. Les webhooks de Stripe ne prennent actuellement pas en charge TLS 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 les événements venant de Stripe peut être modifiée dans la section Webhooks du Dashboard. Pour chaque point de terminaison, cliquez sur Échanger la clé secrète. Vous pouvez choisir de faire invalider 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. Pendant cette période, plusieurs clés secrètes sont actives pour le point de terminaison. Stripe génère une signature par clé secrète jusqu’à son expiration. Afin d’assurer leur sécurité, nous recommandons d’échanger périodiquement les clés secrètes ou de le faire lorsque vous soupçonnez que l’une d’entre elles a été compromise.
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 venant de ces adresses IP.
De plus, vérifiez les signatures des webhooks pour confirmer que les événements reçus sont envoyés par Stripe. 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 été envoyés par Stripe et non par un tiers. Vous pouvez vérifier les signatures soit en utilisant nos bibliothèques officielles, soit en effectuant la vérification manuellement au moyen de votre propre solution.
La section suivante décrit comment vérifier les signatures de webhook :
- Récupérez la clé secrète de votre point de terminaison.
- Vérifiez la signature.
Récupération de la clé secrète de votre point de terminaison
Utilisez la section Webhooks du Dashboard. Sélectionnez un point de terminaison pour lequel vous souhaitez obtenir la clé secrète et repérez la clé secrète en haut à droite de la page.
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 mode test et de mode production, la clé secrète est 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, puis Stripe commence à 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 rapidement renvoyer un code d’état réussi (2xx
) avant de renvoyer 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 comptable.