# Webhook-Versionierung handhaben

Erfahren Sie, wie Sie die API-Version Ihres Webhook-Endpoints aktualisieren.

> [Thin-Ereignisse](https://docs.stripe.com/event-destinations.md#thin-events) für API v1-Ressourcen sind in einer privaten Vorschau verfügbar. Sie können sie verwenden, um Integrations-Upgrades ohne Änderungen an Ihrer Webhook-Konfiguration zu optimieren. Bislang haben Thin-Ereignisse nur API v2-Ressourcen unterstützt. [Erfahren Sie mehr und beantragen Sie Zugang](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog).

Webhook-Endpoints verfügen entweder über eine bestimmte API-Version oder verwenden die Standard-API-Version des Stripe-Kontos. Wenn Sie eines unserer statischen Sprach-SDKs (.NET, Java oder Go) zum Verarbeiten von Ereignissen verwenden, sollte die für Webhooks festgelegte API-Version mit der Version übereinstimmen, die zum Generieren der SDKs verwendet wurde. Der Abgleich dieser Versionen stellt eine erfolgreiche Deserialisierung des Ereignisobjekts sicher.

Verwenden Sie diesen Leitfaden, um Ihre Webhook-Endpoints sicher auf eine neuere API-Version zu aktualisieren, die möglicherweise fehlerhafte Änderungen aufweist.

## Finden Sie heraus, ob die neue API-Version fehlerhafte Änderungen aufweist

Jede API-Version vor [2024-09-30.acacia](https://docs.stripe.com/changelog/acacia.md#2024-09-30.acacia) hat wichtige Änderungen.

Beginnend mit der Veröffentlichung von `2024-09-30.acacia` folgt ein [neuer API-Release-Prozess](https://stripe.com/blog/introducing-stripes-new-api-release-process), bei dem Stripe monatlich neue API-Versionen ohne wesentliche Änderungen veröffentlicht. Zweimal im Jahr veröffentlichen wir eine neue Version (z. B. Acacia), die mit einer API mit wesentlichen Änderungen beginnt. Sie können Ihre Webhook-Endpoints sicher auf jede API-Version derselben Veröffentlichung aktualisieren, ohne Änderungen an Ihrer Integration vorzunehmen.

## Einen neuen deaktivierten Webhook-Endpoint erstellen

Erstellen Sie einen neuen Webhook-Endpoint mit den folgenden Parametern:

- `url`: dieselbe URL wie Ihr ursprünglicher Webhook-Endpoint, aber fügen Sie einen Abfrageparameter hinzu, um zwischen Ereignissen zu unterscheiden, die an die beiden verschiedenen Endpoints gesendet werden. Zum Beispiel `https://example.com/webhooks?version=2024-04-10`.
- `enabled_events`: dieselben Ereignisse wie Ihr ursprünglicher Webhook-Endpoint.
- `api_version`: die API-Version, auf die Sie das Upgrade durchführen möchten. Wenn Sie auf die neueste API-Version aktualisieren, können Sie den Endpoint über das Dashboard oder die API erstellen. Verwenden Sie für andere Versionen die API, um eine bestimmte Version festzulegen.

Deaktivieren Sie den neuen Webhook-Endpoint, nachdem Sie ihn erstellt haben. Im nächsten Schritt werden Sie ihn wieder aktivieren.
![Zwei Endpoints, aber nur der alte sendet Ereignisse](https://b.stripecdn.com/docs-statics-srv/assets/diagram-1.ac21ab637180179813f503649b543e99.png)

## Aktualisieren Sie Ihren Webhook-Code so, dass an den neuen Endpoint gesendete Ereignisse ignoriert werden

Aktualisieren Sie Ihren Code für die Ereignisverarbeitung:

- Wenn der Abfrageparameter für die ältere API-Version gilt, verarbeiten Sie ihn wie gewohnt.
- Wenn der Abfrageparameter für die neuere API-Version gilt, ignorieren Sie das Ereignis und geben Sie eine 200-Antwort zurück, um erneute Übermittlungsversuche zu verhindern.

Aktivieren Sie als Nächstes den neuen Webhook-Endpoint, den Sie im vorherigen Schritt erstellt haben. Zu diesem Zeitpunkt wird jedes Ereignis zweimal gesendet: einmal mit der alten API-Version und einmal mit der neuen.
![Zwei Endpoints, die Ereignisse senden, aber nur den alten verarbeiten](https://b.stripecdn.com/docs-statics-srv/assets/diagram-2.f6b4d3cc0c78971b721fe173f19d5e28.png)

## Aktualisieren Sie Ihren Webhook-Code so, dass Ereignisse für den neuen Endpoint verarbeitet werden

Aktualisieren Sie die Version Ihrer Stripe-Bibliothek, um sie an die Version Ihres neuen Webhook-Endpoints anzupassen. Sehen Sie sich unbedingt das Änderungsprotokoll an und gehen auf alle wichtigen Änderungen ein.

Aktualisieren Sie Ihren Code für die Ereignisverarbeitung:

- Wenn der Abfrageparameter für die ältere Version gilt, ignorieren Sie das Ereignis. Wir empfehlen, einen 400-Status zurückzugeben, damit Stripe das Ereignis automatisch wiederholen kann. Dadurch wird sichergestellt, dass Ereignisse beim Zurücksetzen erneut an den älteren Webhook-Endpoint gesendet werden.
- Wenn der Abfrageparameter für die neue Version gilt, verarbeiten Sie ihn.
![Zwei Endpoints, die Ereignisse senden, aber nur den neuen verarbeiten](https://b.stripecdn.com/docs-statics-srv/assets/diagram-3.8a8b9da70ed66eca60434d406c82f476.png)

## Neuen Webhook-Endpoint überwachen

Wenn Ereignisse von Ihrem neuen Code nicht korrekt gehandhabt werden, versuchen Sie Folgendes:

1. Kehren Sie zur früheren Version Ihres Codes zurück.
2. Den neuen Webhook-Endpoint vorübergehend deaktivieren.
3. Wickeln Sie die fehlgeschlagenen Ereignisse ab (wenn Sie wie im vorherigen Schritt beschrieben einen 400-Status zurückgegeben haben, sendet Stripe alle Ereignisse automatisch erneut).
4. Suchen Sie nach dem Fehler und beheben Sie das Problem.
5. Aktivieren Sie den neuen Webhook-Endpoint und setzen Sie die Überwachung fort.

## Den alten Webhook-Endpoint deaktivieren

Deaktivieren Sie nach einem erfolgreichen Upgrade den alten Webhook-Endpoint, um zu verhindern, dass Ihr Server einen `400`-Status zurückgibt. Wenn Sie ihn nicht deaktivieren, kann dies zu Problemen mit Integrationen führen, die auf eine `200`-Antwort angewiesen sind.

Nachdem Sie den alten Webhook-Endpoint deaktiviert haben, wird Stripe keine Ereignisse erneut zustellen, die einen `400`-Status zurückgegeben haben.
![Zwei Endpoints, aber nur der neue sendet Ereignisse](https://b.stripecdn.com/docs-statics-srv/assets/diagram-4.907bbd1016f9fbe79283e8c35be7f3cd.png)