Gérer le contrôle des versions de webhook

Découvrez comment mettre à niveau la version de l'API de votre endpoint de webhook.

Les endpoints de webhook ont une version API spécifique ou utilisent la version API par défaut du compte Stripe. Si vous utilisez l’un de nos SDK en langage statique (.NET, Java ou Go) pour traiter les événements, la version de l’API définie pour les webhooks doit correspondre à la version utilisée pour générer les SDK. La correspondance de ces versions garantit la réussite de la désérialisation de l’objet de l’événement.

Utilisez ce guide pour mettre à niveau vos endpoints de webhook vers une version plus récente de l’API qui peut comporter des modifications importables.

Déterminer si la nouvelle version de l’API comporte des modifications importantes

Toutes les versions de l’API antérieures au 30/09/2024.acacia comporte des modifications importantes.

À partir de la version 2024-09-30.acacia, Stripe suit un nouveau processus de publication d’API dans lequel nous publions de nouvelles versions d’API tous les mois sans modification importante. Deux fois par an, nous publions une nouvelle version (par exemple acacia) qui commence avec une version de l’API comportant des modifications importantes. Vous pouvez mettre à niveau vos endpoints de webhook en toute sécurité vers n’importe quelle version de l’API dans la même version sans apporter de modifications à votre intégration.

Créer un nouvel endpoint de webhook désactivé

Créez un nouvel endpoint de webhook avec les paramètres suivants :

url : la même URL que votre endpoint de webhook origine, à laquelle vous ajoutez un paramètre de requête pour distinguer les événements envoyés aux deux différents endpoints. Par exemple, https://example.com/webhooks?version=2024-04-10.
enabled_events : les mêmes événements que votre endpoint de webhook d’origine.
api_version: la version d’API à laquelle vous souhaitez passer. Si vous faites une mise à niveau vers la dernière version de l’API, vous pouvez utiliser le Dashboard ou l’API pour créer l’endpoint. Pour les autres versions, utilisez l’API pour configurer une version spécifique.

Après avoir créé le nouvel endpoint de webhook, désactivez-le. Vous le réactiverez à l’étape suivante.

Deux endpoints, mais seul le plus ancien envoie des événements

Mettez à jour le code de votre webhook afin d’ignorer les événements envoyés vers le nouvel endpoint

Mettez à jour votre code de traitement des événements :

Si le paramètre de la requête concerne l’ancienne version de l’API, traitez-le comme d’habitude.
Si le paramètre de la requête concerne la version la plus récente de l’API, ignorez l’événement et renvoyez une réponse 200 afin d’éviter les tentatives d’envoi.

Ensuite, activez le nouvel endpoint de webhook que vous avez créé à l’étape précédente. À ce stade, chaque événement est envoyé deux fois : une fois avec l’ancienne version de l’API et une fois avec la nouvelle.

Deux endpoints envoient des événements, mais seuls ceux du plus ancien sont traités

Mettez à jour le code de votre webhook afin de traiter les événements concernant le nouvel endpoint

Mettez à jour la version de la bibliothèque Stripe que vous utilisez pour qu’elle corresponde à la version de votre nouvel endpoint de webhook. Assurez-vous de lire le log des modifications et de gérer les modifications importantes.

Mettez à jour votre code de traitement des événements :

Si le paramètre de la requête concerne la version la plus ancienne, ignorez l’événement. Nous vous recommandons de renvoyer un code d’état 400 pour permettre à Stripe de réessayer automatiquement l’événement. Ainsi, si vous avez besoin d’annuler, vous aurez la garantie que les événements sont renvoyés à l’ancien endpoint de webhook.
Si le paramètre de la requête concerne la nouvelle version, traitez-le.

Deux endpoints envoient des événements, mais seuls ceux du plus récent sont traités

Surveillez votre nouvel endpoint de webhook

Si les événements ne sont pas gérés correctement par votre nouveau code, essayez ce qui suit :

Revenez à la version précédente de votre code.
Désactivez temporairement le nouvel endpoint de webhook.
Traitez les événements en échec (si vous avez renvoyé un code d’état 400 comme indiqué à l’étape précédente, Stripe renvoie automatiquement tous les événements).
Enquêtez sur le problème et résolvez-le.
Activez le nouvel endpoint de webhook et reprenez la surveillance.

Désactivez l’ancien endpoint de webhook

Une fois la mise à niveau effectuée, désactivez l’ancien endpoint de webhook pour empêcher votre serveur de renvoyer l’état 400. Si vous ne le désactivez pas, cela peut entraîner des problèmes avec les intégrations qui dépendent d’une réponse 200.

Une fois que vous avez désactivé l’ancien endpoint de webhook, Stripe n’envoie plus les événements qui ont renvoyé un 400.

Deux endpoints, mais seul le plus récent envoie des événements