Utilisation des webhooks avec les abonnements

Découvrez comment utiliser les webhooks pour recevoir des notifications en cas d'activité liées à vos abonnements.

Vous recevez des notifications de Stripe dans votre application par le biais d’événements de webhook. Utilisez des événements de webhook pour gérer les abonnements, car la plupart des activités se déroulent de manière asynchrone. Traitez ces événements au niveau d’un endpoint de webhook ou d’autres destinations telles qu’Amazon EventBridge en créant une destination d’événement.

Pour utiliser les webhooks avec vos abonnements :

Créez un endpoint de webhook dans votre application.
Inscrire votre endpoint de webhook dans Workbench
Ajoutez la logique voulue pour gérer les événements Stripe. Pour les abonnements, il s’agit principalement de traiter les échecs de paiement et les changements d’état de l’abonnement (comme le basculement d’une période d’essai à l’état actif). Vous pouvez utiliser le guide de démarrage rapide du webhook pour créer un endpoint de webhook minimal.
Testez votre endpoint de webhook pour confirmer qu’il fonctionne comme prévu.

Si votre application s’exécute sur AWS, vous pouvez configurer Stripe de façon à envoyer les événements directement à AWS EventBridge dans votre compte AWS.

Événements d'abonnement

Stripe déclenche des événements chaque fois qu’un abonnement est créé ou modifié. Certains événements sont envoyés dès la création de l’abonnement, tandis que d’autres se répètent régulièrement à l’occasion de chaque facturation.

Veillez à ce que votre intégration gère les événements de manière adéquate. Par exemple, vous pouvez envoyer un e-mail à votre client en cas d’échec de paiement ou révoquer son accès s’il annule son abonnement.

Le tableau suivant décrit les événements les plus courants liés aux abonnements et, le cas échéant, suggère les actions à entreprendre pour les gérer.



`customer.created`	Envoyé lorsqu’un objet Customer a bien été créé.
`customer.subscription.created`	Envoyé lors de la création de l’abonnement. Le `status` de l’abonnement peut être `incomplete` si l’authentification du client est demandée pour mener à bien le paiement ou si vous définissez `payment_behavior` sur `default_incomplete`. Familiarisez-vous avec le comportement de paiement des abonnements pour en savoir plus.
`customer.subscription.deleted`	Envoyé lorsque l’abonnement d’un client prend fin.
`customer.subscription.paused`	Envoyé lorsque le `status` d’un abonnement passe à `paused`. Par exemple, l’événement est envoyé lorsqu’un abonnement est configuré pour être suspendu lorsqu’un essai gratuit prend fin sans moyen de paiement. La facturation n’aura pas lieu tant que l’abonnement n’aura pas repris. Nous n’envoyons pas cet événement si l’encaissement des paiements est suspendu, car des factures continuent d’être créées pendant cette période.
`customer.subscription.resumed`	Envoyé lors de la reprise d’un abonnement qui était à l’état `paused`. Cela ne s’applique pas lorsque l’encaissement des paiements est réactivé.
`customer.subscription.trial_will_end`	Envoyé trois jours avant la fin de la période d’essai. Si la période d’essai est inférieure à trois jours, l’événement est déclenché.
`customer.subscription.updated`	Envoyé lorsqu’un abonnement démarre ou est modifié. Par exemple, le renouvellement d’un abonnement, l’ajout d’un bon de réduction, l’application d’une réduction, l’ajout d’un poste de facture et le changement de plan déclenchent sont des situations qui déclenchent cet événement.
`entitlements.active_entitlement_summary.updated`	Envoyé lorsque les droits actifs d’un client sont mis à jour. Lorsque vous recevez cet événement, vous pouvez donner ou retirer l’accès aux fonctionnalités de votre produit. En savoir plus sur l’intégration des droits.
`invoice.created`	Envoyé lorsqu’une facture est créée pour un nouvel abonnement ou un renouvellement. Si Stripe ne reçoit pas une réponse positive à `invoice.created`, la finalisation de toutes les factures avec l’encaissement automatique est retardée de 72 heures au maximum. Renseignez-vous sur la finalisation des factures. Répondez à la notification en envoyant une requête à l’API de finalisation des factures.
`invoice.finalized`	Envoyé lorsqu’une facture est finalisée et prête à être payée. Vous pouvez envoyer la facture au client. Familiarisez-vous avec la finalisation des factures pour en savoir plus. Selon vos paramètres, nous débitons automatiquement le moyen de paiement par défaut ou tentons un encaissement. Renseignez-vous sur les e-mails après la finalisation pour en savoir plus.
`invoice.finalization_failed`	La facture n’a pas pu être finalisée. Reportez-vous à la page consacrée à la gestion des échecs de finalisation des factures. Davantage d’informations à propos de la finalisation des factures sont disponibles dans le guide de présentation générale des factures. Inspectez e champ `last_finalization_error` de l’objet Invoice pour déterminer la cause de l’erreur. Si vous utilisez Stripe Tax, vérifiez le champ automatic_tax de l’objet Invoice. Si `automatic_tax[status]=requires_location_inputs`, la facture ne peut pas être finalisée et les paiements ne sont pas perçus. Prévenez votre client et collectez la localisation du client demandée. Si `automatic_tax[status]=failed`, relancez la requête plus tard.
`invoice.paid`	Envoyé lorsque la facture est réglée. Vous pouvez fournir l’accès à votre produit dès la réception de cet événement et le basculement du `status` de l’abonnement sur `active`.
`invoice.payment_action_required`	Envoyé lorsque la facture nécessite une authentification du client. Découvrez comment gérer un abonnement quand une action est requise pour la facture.
`invoice.payment_failed`	Le paiement d’une facture a échoué. L’état du PaymentIntent bascule sur `requires_action`. L’état de l’abonnement reste `incomplete` seulement pour la première facture de l’abonnement. Lorsqu’un paiement échoue, plusieurs actions sont possibles : Prévenez votre client. Apprenez à configurer les paramètres d’abonnement pour activer les relances intelligentes Smart Retries et d’autres fonctionnalités d’encaissement. Si vous utilisez des PaymentIntents, recueillez de nouvelles données de paiement et confirmez le PaymentIntent. Mettez à jour le moyen de paiement par défaut de l’abonnement.
`invoice.upcoming`	Envoyé quelques jours avant le renouvellement de l’abonnement. Le nombre de jours dépend de la valeur Événements de renouvellement à venir configurée dans le Dashboard. Pour les abonnements existants, la modification du nombre de jours prend effet à la période de facturation suivante. Vous pouvez toujours ajouter des postes de facture supplémentaires si nécessaire.
`invoice.updated`	Envoyé lorsqu’un paiement aboutit ou échoue. Si le paiement aboutit, l’attribut `paid` est défini sur `true` et le `status` sur `paid`. Si le paiement échoue, `paid` est défini sur `false` et le `status` reste `open`. Les échecs de paiement déclenchent par ailleurs un événement `invoice.payment_failed`.
`payment_intent.created`	Envoyé lorsqu’un PaymentIntent est créé.
`payment_intent.succeeded`	Envoyé lorsqu’un PaymentIntent a effectué un paiement avec succès.
`subscription_schedule.aborted`	Envoyé lorsqu’une planification d’abonnement est annulée car un défaut de paiement a entraîné la résiliation de l’abonnement correspondant.
`subscription_schedule.canceled`	Envoyé lorsqu’une planification d’abonnement est annulée, ce qui annule également tout abonnement actif associé.
`subscription_schedule.completed`	Envoyé lorsque toutes les phases d’une planification d’abonnement sont terminées.
`subscription_schedule.created`	Envoyé lorsqu’une nouvelle planification d’abonnement est créée.
`subscription_schedule.expiring`	Envoyé 7 jours avant la date d’expiration d’un abonnement.
`subscription_schedule.released`	Envoyé lorsqu’une planification d’abonnement est publiée, ou interrompue et dissociée de l’abonnement, lequel est conservé.
`subscription_schedule.updated`	Envoyé lorsqu’une planification d’abonnement est mise à jour.

Gérer les échecs de paiement

Les événements constituent un moyen sûr pour Stripe de vous informer des échecs de paiement de vos factures d’abonnement. Certains échecs de paiement sont temporaires : par exemple, l’émetteur de la carte peut refuser le débit initial, mais autoriser une nouvelle tentative automatique par la suite. D’autres échecs de paiement sont en revanche définitifs, comme ceux liés à l’absence de moyen de paiement utilisable pour le client, et nécessitent une action.

Événement Description

Événement	Description
`invoice.payment_failed`	Le paiement d’une facture a échoué. L’état du PaymentIntent passe à `requires_payment_method`. L’état de l’abonnement passe à `incomplete`. En cas d’échec de paiement, plusieurs actions sont possibles : Prévenez votre client. Si vous utilisez des PaymentIntents, recueillez de nouvelles données de paiement et confirmez le PaymentIntent. Mettez à jour le moyen de paiement par défaut de l’abonnement. Envisagez d’activer les relances Smart Retries.

invoice.payment_failed

Le paiement d’une facture a échoué. L’état du PaymentIntent passe à requires_payment_method. L’état de l’abonnement passe à incomplete. En cas d’échec de paiement, plusieurs actions sont possibles :

Prévenez votre client.
Si vous utilisez des PaymentIntents, recueillez de nouvelles données de paiement et confirmez le PaymentIntent.
Mettez à jour le moyen de paiement par défaut de l’abonnement.
Envisagez d’activer les relances Smart Retries.

Gérer les paiements nécessitant une action supplémentaire

Certains moyens de paiement peuvent nécessiter des étapes supplémentaires, comme une authentification du client, pour que l’opération puisse aboutir. Si vous recevez de tels événements, votre application doit notifier le client pour qu’il effectue l’action requise. Pour plus d’informations sur la façon de gérer les événements nécessitant une action supplémentaire, consultez le guide de présentation des abonnements.

Événement Description

Événement	Description
`invoice.finalization_failed`	La facture n’a pas pu être finalisée. Reportez-vous à la page consacrée à la gestion des échecs de finalisation des factures. Davantage d’informations à propos de la finalisation des factures sont disponibles dans le guide de présentation générale des factures. Inspectez le champ last_finalization_error de l’objet Invoice pour déterminer la cause de l’erreur. Si vous utilisez Stripe Tax, vérifiez le champ automatic_tax de l’objet Invoice. Si `automatic_tax[status]=requires_location_inputs`, la facture ne peut pas être finalisée et les paiements ne sont pas perçus. Prévenez votre client et collectez la localisation du client demandée. Si `automatic_tax[status]=failed` s’affiche, réessayez la requête plus tard.
`invoice.payment_failed`	Le paiement d’une facture a échoué. L’état du PaymentIntent passe à `requires_action`. L’état de l’abonnement passe à `incomplete`. En cas d’échec de paiement, plusieurs actions sont possibles : Prévenez votre client. Si vous utilisez des PaymentIntents, recueillez de nouvelles données de paiement et confirmez le PaymentIntent. Mettez à jour le moyen de paiement par défaut de l’abonnement. Envisagez d’activer les relances Smart Retries.
`invoice.payment_action_required`	Le paiement d’une facture a échoué. L’état du PaymentIntent passe à `requires_action`. L’état de l’abonnement passe à `incomplete`. En cas d’échec de paiement, plusieurs actions sont possibles : Prévenez votre client. Si vous utilisez des PaymentIntents, recueillez de nouvelles données de paiement et confirmez le PaymentIntent. Mettez à jour le moyen de paiement par défaut de l’abonnement. Envisagez d’activer les relances Smart Retries.

invoice.finalization_failed

La facture n’a pas pu être finalisée. Reportez-vous à la page consacrée à la gestion des échecs de finalisation des factures. Davantage d’informations à propos de la finalisation des factures sont disponibles dans le guide de présentation générale des factures.

Inspectez le champ last_finalization_error de l’objet Invoice pour déterminer la cause de l’erreur.
Si vous utilisez Stripe Tax, vérifiez le champ automatic_tax de l’objet Invoice.
Si automatic_tax[status]=requires_location_inputs, la facture ne peut pas être finalisée et les paiements ne sont pas perçus. Prévenez votre client et collectez la localisation du client demandée.
Si automatic_tax[status]=failed s’affiche, réessayez la requête plus tard.

invoice.payment_failed

Le paiement d’une facture a échoué. L’état du PaymentIntent passe à requires_action. L’état de l’abonnement passe à incomplete. En cas d’échec de paiement, plusieurs actions sont possibles :

Prévenez votre client.
Si vous utilisez des PaymentIntents, recueillez de nouvelles données de paiement et confirmez le PaymentIntent.
Mettez à jour le moyen de paiement par défaut de l’abonnement.
Envisagez d’activer les relances Smart Retries.

invoice.payment_action_required

Prévenez votre client.
Si vous utilisez des PaymentIntents, recueillez de nouvelles données de paiement et confirmez le PaymentIntent.
Mettez à jour le moyen de paiement par défaut de l’abonnement.
Envisagez d’activer les relances Smart Retries.

Suivre les abonnements actifs

Les abonnements nécessitent une coordination entre votre site et Stripe. La réussite ou l’échec des paiements récurrents d’un client détermine s’il peut continuer à accéder à votre produit ou service.

Dans une intégration type, vous stockez les identifiants de vos clients et une valeur d’horodatage associée qui représente la date d’expiration de l’accès du client sur votre site lorsqu’un client s’abonne. Lorsque le client se connecte, vous pouvez vérifier si l’horodatage est toujours dans le futur. Si c’est le cas lors de la connexion du client, le compte est actif et le client doit toujours avoir accès au service.

Lors du renouvellement de l’abonnement, Stripe facture le client et tente de percevoir le paiement en débitant automatiquement le moyen de paiement enregistré ou en envoyant la facture par e-mail aux clients. Stripe informe votre site de l’état de la facture par l’envoi d’un événement de webhook :

Votre site reçoit un événement invoice.paid.
- Lors du débit automatique d’un moyen de paiement, votre site reçoit d’abord un événement invoice.upcoming sur l’endpoint de votre webhook configuré quelques jours avant le renouvellement. Vous pouvez écouter cet événement pour ajouter des postes supplémentaires à la facture à venir. En présence du paramètre collection_method=send_invoice, Stripe n’envoie pas d’événement invoice.upcoming.
Votre application trouve le client pour lequel le paiement a été effectué.
Votre application met à jour la date d’expiration de l’accès du client dans votre base de données sur la date à venir appropriée (plus un ou deux jour(s) de marge).

Capturer les changements d’état des abonnements

Assurez-vous que votre intégration surveille et gère correctement les changements d’état des abonnements décrits dans le tableau suivant.

Certaines modifications d’état requièrent une attention particulière :

Quelques jours avant la fin de la période d’essai et le passage de l’abonnement de l’état trialing à active, vous recevez un événement customer.subscription.trial_will_end. À la réception de cet événement, vérifiez qu’un moyen de paiement est défini pour le client afin de pouvoir le facturer. Si vous le souhaitez, vous pouvez prévenir le client qu’il va être débité.
Lorsqu’un abonnement bascule à l’état past_due, prévenez votre client directement et demandez-lui de mettre ses données de paiement à jour. Stripe propose plusieurs fonctionnalités pour automatiser ce processus. Reportez-vous à la page consacrée au recouvrement de revenus.
Lorsqu’un abonnement passe à l’état canceled ou unpaid, révoquez l’accès à votre produit.

État	Description
`trialing`	L’abonnement est actuellement en période d’essai et vous pouvez fournir votre produit à votre client en toute sécurité. L’abonnement passe automatiquement à l’état `active` lorsqu’un client effectue son premier paiement.
`active`	L’abonnement est en règle. Pour les abonnements `past_due`, le paiement de la dernière facture associée ou son marquage comme irrécouvrable fait passer l’abonnement à l’état `active`. Notez que la valeur `active` n’indique pas que toutes les factures impayées associées à l’abonnement ont été réglées. Vous pouvez laisser les autres factures impayées en cours de paiement, les marquer comme irrécouvrables ou les annuler, selon vos besoins.
`incomplete`	Le client doit effectuer un paiement dans les 23 heures suivant la création de l’abonnement pour l’activer. Ou une action est requise pour le paiement, telle que l’authentification du client. Les abonnements peuvent également être à l’état `incomplete` si un paiement est en attente et que l’état du PaymentIntent est défini sur `processing`.
`incomplete_expired`	Le paiement initial de l’abonnement a échoué et le client n’a pas effectué de paiement dans les 23 heures suivant la création de l’abonnement. Ces abonnements ne facturent pas les clients. Cet état vous permet de suivre les clients qui n’ont pas réussi à activer leur abonnement.
`past_due`	Le paiement de la dernière facture finalisée a échoué ou n’a pas été tenté. L’abonnement continue de générer des factures. Vos paramètres d’abonnement déterminent le prochain état de l’abonnement. Si la facture n’est toujours pas réglée après toutes les tentatives de relances intelligentes, vous pouvez configurer l’abonnement pour qu’il passe à l’état`canceled`, `unpaid` ou le laisser à l’état `past_due`. Pour réactiver l’abonnement, demandez à votre client de payer la dernière facture. L’état de l’abonnement devient `active`, que le paiement soit effectué avant ou après la dernière date d’échéance de la facture.
`canceled`	L’abonnement a été annulé. Lors de l’annulation, l’encaissement automatique de toutes les factures impayées est désactivé (`auto_advance=false`). Cet état est définitif et ne peut pas être mis à jour.
`unpaid`	La dernière facture n’a pas été réglée, mais l’abonnement reste actif. La dernière facture reste ouverte et les factures continuent d’être générées, mais aucune tentative de paiement n’est effectuée. Révoquez l’accès à votre produit lorsque l’abonnement passe à l’état `unpaid`, car des tentatives de paiement ont déjà été effectués à plusieurs reprises lorsque qu’il était à l’état `past_due`. Pour passer l’abonnement à l’état `active`, la facture la plus récente doit être réglée avant sa date d’échéance.
`paused`	L’abonnement a terminé sa période d’essai sans moyen de paiement par défaut et le paramètre trial_settings.end_behavior.missing_payment_method est défini sur `pause`. Aucune facture n’est plus créée pour l’abonnement. Après avoir associé un moyen de paiement par défaut au client, vous pouvez reprendre l’abonnement.

Endpoints de webhook et factures

Enregistrez un endpoint de webhook pour garder une trace des états de la facture. L’intégration de vos abonnements dépend de la finalisation des factures et de la gestion appropriées des échecs de finalisation.

Lorsque vous activez l’encaissement automatique, Stripe finalise automatiquement la facture et lance son encaissement automatique.

Si Stripe ne reçoit pas de réponse positive à invoice.created, nous retardons la finalisation de toutes les factures avec l’encaissement automatique de 72 heures au maximum, à l’exception de celles pour lesquelles vous avez défini une date/heure de finalisation planifiée.
Pour répondre correctement à invoice.created, il faut gérer tous les endpoints de webhook configurés pour votre compte, ainsi que les endpoints de webhook de toutes les plateformes auxquelles vous vous êtes connecté. Les endpoints de webhook configurés dans une organisation ne sont pas pris en compte. Bien que vous puissiez écouter invoice.created au niveau de l’organisation, une réponse positive n’affecte pas la finalisation de la facture lors de l’utilisation du recouvrement automatique.
Mettre à jour un abonnement pour tenter des paiements en mode synchrone (sur la facture initiale et certaines mises à jour) n’entraîne pas ce délai.
L’échec de la finalisation de la facture empêche l’encaissement du paiement correspondant. Assurez-vous d’écouter l’événement invoice.finalization_failed dans votre endpoint de webhook.

Voir la liste complète des types d’événements de facturation.

Événement	Description
`invoice.created`	La facture a été créée et peut être finalisée. Consultez la documentation pour en savoir plus sur la finalisation des factures. Répondez à la notification en envoyant une requête à l’API de finalisation des factures.
`invoice.finalized`	La facture a été finalisée et est prête à être payée. Vous pouvez envoyer la facture au client. Renseignez-vous sur la finalisation des factures. Selon vos paramètres, Stripe débite automatiquement le moyen de paiement par défaut ou tente un encaissement. Renseignez-vous sur les e-mails post-finalisation.
`invoice.finalization_failed`	La facture n’a pas pu être finalisée. Reportez-vous à la page consacrée à la gestion des échecs de finalisation des factures. Davantage d’informations à propos de la finalisation des factures sont disponibles dans le guide de présentation générale des factures. Inspectez le champ last_finalization_error de l’objet Invoice pour déterminer la cause de l’erreur. Si vous utilisez Stripe Tax, vérifiez le champ automatic_tax de l’objet Invoice. Si `automatic_tax[status]=requires_location_inputs`, la facture ne peut pas être finalisée et les paiements ne sont pas perçus. Prévenez votre client et collectez la localisation du client demandée. Si `automatic_tax[status]=failed`, relancez la requête ultérieurement.

Finalisation de facture réussie

Stripe attend une heure après réception d’une réponse de réussite pour l’événement invoice.created avant de tenter le paiement. Si nous ne recevons aucune réponse de réussite dans les 72 heures, nous tentons de finaliser la facture et de l’envoyer.

Si vous souhaitez traiter les factures ponctuelles différemment des factures d’abonnement, cochez la propriété subscription dans le corps du webhook. Ceci permet d’indiquer si la facture a été créée pour un abonnement.

En mode production, si votre endpoint de webhook ne renvoie pas de réponse correcte, Stripe continue de tenter la notification de webhook pendant 3 jours au maximum, avec un allongement exponentiel des délais. Dans un environnement de test, nous procédons à trois tentatives sur une période de quelques heures. Pendant ce temps, nous ne tenterons pas de débiter le client tant que nous n’aurons pas reçu une réponse positive. Nous vous enverrons également un e-mail en cas d’échec du webhook.

Ce comportement s’applique à tous les endpoints de webhook définis sur votre compte, y compris les cas où une application Stripe Connect ou un service tiers rencontre des problèmes pour gérer les webhooks entrants.

Échec de la finalisation de facture

Lorsque Stripe n’est pas en mesure de finaliser une facture, il envoie un événement invoice.finalization_failed à votre endpoint de webhook. Un abonnement reste actif lorsqu’une facture ne peut pas être finalisée, ce qui signifie que l’utilisateur reste en capacité d’accéder à votre produit tandis que vous ne pouvez pas percevoir ses paiements. Veillez à prendre les mesures utiles pour vos factures non finalisées. Vous ne pouvez pas percevoir de paiements pour une facture qui n’a pas été finalisée.

Pour déterminer la raison de l’échec de la finalisation de la facture, inspectez le champ last_finalization_error de l’objet Invoice, qui vous fournira davantage d’informations sur l’échec et vous renseignera sur la manière d’y remédier.

Si vous utilisez Stripe Tax, vérifiez si le champ automatic_tax.status correspond à requires_location_inputs, ce qui signifie que les coordonnées de l’adresse ne sont pas valides ou sont insuffisantes. Si Stripe Tax ne trouve pas de localisation client reconnue, nous ne pouvons pas finaliser la facture. Découvrez comment gérer les échecs de finalisations de facture.

Tests

Pour tester votre endpoint de webhook ou votre destination d’événement, choisissez l’une des deux options suivantes :

Utilisez un environnement de test pour effectuer des actions qui envoient des événements légitimes à votre destination d’événements. Par exemple, vous pouvez utiliser une carte de test amenant un paiement à aboutir pour déclencher l’événement charge.succeeded.
Déclenchez des événements à l’aide de l’interface de ligne de commande Stripe ou via Stripe pour Visual Studio Code.