Webhook-Versionierung handhaben
Erfahren Sie, wie Sie die API-Version Ihres Webhook-Endpoints aktualisieren.
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. wichtige Änderungen enthalten.
Ab der Version 2024-09-30.acacia folgt Stripe einem neuen API-Veröffentlichungsprozess, bei dem wir monatlich neue API-Versionen ohne Änderungen freigeben. Zweimal im Jahr veröffentlichen wir eine neue Version (zum Beispiel acacia), die mit einer API-Version beginnt, die wichtige Änderungen enthält. Sie können Ihre Webhook-Endpoints sicher auf eine beliebige API-Version in derselben Version aktualisieren, ohne Änderungen an Ihrer Integration vorzunehmen.
Einen neuen deaktivierten Webhook-Endpoint erstellen
Erstellen Sie einen neuen Webhook-Endpoint mit den folgenden Parametern:
url: die gleiche URL wie Ihr ursprünglicher Webhook-Endpoint, aber Sie fügen einen Abfrageparameter hinzu, um zwischen den Ereignissen zu unterscheiden, die an die beiden verschiedenen Endpoints gesendet werden. Zum Beispielhttps://example..com/webhooks?version=2024-04-10 enabled_: dieselben Ereignisse wie Ihr ursprünglicher Webhook-Endpoint.events api_: 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.version
Deaktivieren Sie den neuen Webhook-Endpoint, nachdem Sie ihn erstellt haben. Im nächsten Schritt werden Sie diesen wieder aktivieren.
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.
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.
Neuen Webhook-Endpoint überwachen
Wenn Ereignisse von Ihrem neuen Code nicht korrekt gehandhabt werden, versuchen Sie Folgendes:
- Kehren Sie zur früheren Version Ihres Codes zurück.
- Den neuen Webhook-Endpoint vorübergehend deaktivieren.
- Verarbeiten Sie die fehlgeschlagenen Ereignisse (wenn Sie einen 400-Status wie im vorherigen Schritt beschrieben zurückgegeben haben, sendet Stripe alle Ereignisse automatisch erneut).
- Suchen Sie nach dem Fehler und beheben Sie das Problem.
- Aktivieren Sie den neuen Webhook-Endpoint und setzen Sie die Überwachung fort.
Den alten Webhook-Endpoint deaktivieren
Wenn das Upgrade erfolgreich war, können Sie den alten Webhook-Endpoint deaktivieren. Ereignissen, bei denen Sie einen 400-Status zurückgegeben haben, werden nicht erneut übermittelt, nachdem der Webhook-Endpoint deaktiviert wurde.
