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.acacia hat wichtige Änderungen.

Beginnend mit der Veröffentlichung von 2024-09-30.acacia folgt ein neuer API-Release-Prozess, 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: 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 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 diesen wieder aktivieren.

Zwei Endpoints, aber nur der alte sendet Ereignisse

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

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

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

Deaktivieren Sie nach erfolgreichem Upgrade den alten Webhook-Endpoint, damit Ihr Server nicht mehr den Status 400 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, stellt Stripe Ereignisse, die 400 zurückgegeben haben, nicht erneut zu.

Zwei Endpoints, aber nur der neue sendet Ereignisse