Webhook-Versionierung handhaben

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.

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:

1. Kehren Sie zur früheren Version Ihres Codes zurück.
2. Den neuen Webhook-Endpoint vorübergehend deaktivieren.
3. Verarbeiten Sie die fehlgeschlagenen Ereignisse (wenn Sie einen 400-Status wie im vorherigen Schritt beschrieben 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 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.