# 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 [événements légers](https://docs.stripe.com/event-destinations.md#thin-events) pour les ressources de l’API v1 sont disponibles en version bêta privée. Vous pouvez les utiliser pour simplifier les mises à niveau d’intégration sans modifier la configuration de votre webhook. Auparavant, les événements légers prenaient uniquement en charge les ressources de l’API v2. [En savoir plus et demander un accès](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog).

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](https://docs.stripe.com/changelog/acacia.md#2024-09-30.acacia) comporte des modifications importantes.

À partir de la version 2024-09-30.acacia, Stripe suit un [nouveau processus de publication de l’API](https://stripe.com/blog/introducing-stripes-new-api-release-process) en publiant de nouvelles versions de l’API chaque mois sans modifications entraînant une rupture de compatibilité. Deux fois par an, nous publions une nouvelle version majeure (par exemple, [Basil](https://docs.stripe.com/changelog/basil.md)) qui commence par une version de l’API contenant des modifications entraînant une rupture de compatibilité. Vous pouvez passer à n’importe quelle version mensuelle en toute sécurité sans mettre à jour votre code. Le passage à une nouvelle version majeure peut nécessiter des modifications de votre intégration existante.

Vous pouvez mettre à niveau vos endpoints de webhook vers n’importe quelle version d’API de la même version majeure en toute sécurité, sans modifier 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 d’origine, mais ajoutez un paramètre de requête pour différencier les événements envoyés aux deux endpoints différents. 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 webhook, désactivez-le. Vous le réactiverez à l’étape suivante.
![Deux endpoints, mais seul le plus ancien envoie des événements](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png)

## 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](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png)

## 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](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png)

## 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 :

1. Revenez à la version précédente de votre code.
2. Désactivez temporairement le nouvel endpoint de webhook.
3. 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).
4. Enquêtez sur le problème et résolvez-le.
5. Activez le nouvel endpoint de webhook et reprenez la surveillance.

## Désactivez l’ancien endpoint de webhook

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

Après avoir désactivé l’ancien endpoint de webhook, Stripe ne redistribuera pas les événements qui ont renvoyé un `400`.
![Deux endpoints, mais seul le plus récent envoie des événements](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png)