Stripe-Ereignisse in Ihrem Webhook-Endpoint empfangen
Ereignisse an Ihr AWS-Konto senden
Wir unterstützen bald das Empfangen von Stripe-Ereignissen in Amazon EventBridge in unserer privaten Beta-Version. Registrieren Sie sich auf eventbridge.stripe.dev, um frühzeitigen Zugriff zu erhalten.
Gründe für die Verwendung von Webhooks
Beim Erstellen von Stripe-Integrationen möchten Sie möglicherweise, dass Ihre Anwendungen Ereignisse empfangen, wenn sie in Ihren Stripe-Konten auftreten, damit Ihre Backend-Systeme entsprechende Aktionen ausführen können.
Um Webhook-Ereignisse zu aktivieren, müssen Sie Webhook-Endpoints registrieren. Nach der Registrierung kann Stripe Ereignisdaten in Echtzeit an den Webhook-Endpoint Ihrer Anwendung senden, wenn in Ihrem Stripe-Konto Ereignisse stattfinden. Stripe verwendet HTTPS, um Webhook-Ereignisse als JSON-Nutzlast, die ein Ereignisobjekt enthält, an Ihre App zu senden.
Der Empfang von Webhook-Ereignissen ist besonders nützlich, um asynchrone Ereignisse zu überwachen, z. B. wenn die Kundenbank eine Zahlung bestätigt, eine Kundin/ein Kunde eine Zahlung anficht, eine wiederkehrende Zahlung erfolgreich ist oder wenn Sie Abonnementzahlungen einziehen.
Übersicht über Ereignisse
Stripe generiert Ereignisdaten, die wir Ihnen zusenden können, um Sie über Aktivitäten in Ihrem Konto zu informieren.
Wenn ein Ereignis eintritt, generiert Stripe ein neues Ereignisobjekt. Eine einzelne API-Anfrage kann zur Erstellung mehrerer Ereignisse führen. Wenn Sie beispielsweise ein neues Abonnement für eine Kundin/einen Kunden erstellen, erhalten Sie die Ereignisse customer.subscription.created
und payment_intent.succeeded
.
Indem Sie Webhook-Endpoints in Ihrem Stripe-Konto registrieren, ermöglichen Sie es Stripe, automatisch Ereignisobjekte als Teil von POST-Anfragen an den von Ihrer Anwendung gehosteten registrierten Webhook-Endpoint zu senden. Nachdem Ihr Webhook-Endpoint das Ereignis empfangen hat, kann Ihre Anwendung Backend-Aktionen ausführen (also z. B. die APIs Ihres Versanddienstleisters aufrufen, um einen Versand zu planen, nachdem Sie ein payment_intent.succeeded
-Ereignis empfangen haben).
Ereignisobjekt
Das Ereignisobjekt, das wir an Ihren Webhook-Endpoint senden, bietet eine Momentaufnahme des Objekts, das sich geändert hat. Sie können die Eigenschaft previous_attributes
enthalten, die ggf. die Änderung angibt.
Sehen Sie sich die Liste aller Ereignistypen an, die wir an Ihren Webhook senden.
Beispiel für eine Ereignisnutzlast
Das folgende Ereignis zeigt eine Abonnementaktualisierung am Ende eines Testzeitraums.
{ "id": "evt_1MqqbKLt4dXK03v5qaIbiNCC", "object": "event", "api_version": "2024-04-10", "created": 1680064028,
Ereignisobjektstruktur
Überprüfen Sie die Struktur des Ereignisobjekts, um Ereignisse und die zugrunde liegenden Informationen, die sie bereitstellen, besser zu verstehen.
Ereignistyp
Sie erhalten Ereignisse für alle Ereignistypen, die von Ihrem Webhook-Endpoint in Ihrer Konfiguration überwacht werden. Verwenden Sie den type
des empfangenen Ereignisses, um zu bestimmen, welche Verarbeitungsschritte Ihre Anwendung durchführen muss. Das data.object
, das jedem Ereignis-type
entspricht, variiert.
Live- und Testmodus
Möglicherweise erhalten Sie an Ihren Endpoints Anfragen für die Bereitstellung von Ereignissen sowohl im Live- als auch im Test-Modus. Dies kann vorkommen, wenn Sie einen einzigen Endpoint sowohl für den Live- als auch für den Test-Modus verwenden oder wenn Sie eine Connect-Plattform sind, die Test-Modus-Anfragen für verbundene Standardkonten im Live-Modus stellt. Verwenden Sie das Attribut livemode
, um zu prüfen, ob das Objekt im Live- oder im Test-Modus vorliegt und um die korrekte Behandlung des Ereignisses zu bestimmen.
API-Version
Die api_version
gibt die API-Version des Ereignisses an und bestimmt die Struktur des enthaltenen data.object. Ihr Endpoint empfängt Ereignisse unter Verwendung der konfigurierten API-Version, die sich von der Standard-API-Version Ihres Kontos oder der API-Version aller mit dem Ereignis verbundenen Anfragen unterscheiden kann. Dieses Attribut wird durch den Ziel-Endpoint bestimmt, was bedeutet, dass dasselbe Ereignis an mehrere Endpoints mit unterschiedlichen API-Versionen übermittelt werden kann. Wenn Sie unsere Java-, .NET- oder Go-Client-Bibliotheken verwenden, müssen Sie die API-Version des Endpoints unbedingt so konfigurieren, dass dieselbe API-Version verwendet wird, die im Client hinterlegt ist. Andernfalls können Sie die Ereignisobjekte möglicherweise nicht deserialisieren.
Beim Abrufen von Ereignisobjekten von der API können Sie die API-Version der data.object
-Struktur nicht steuern. Rufen Sie stattdessen dieses Objekt vom entsprechenden API-Endpoint ab und verwenden Sie den Stripe-Version
-Header, um eine API-Version anzugeben.
API-Anfrage-Ereignisse
Wenn ein Ereignis in Folge einer API-Anfrage generiert wird, wird diese Anfrage als request.id
angezeigt. Wenn Sie bei der Anfrage einen idempotency_key
verwenden, ist dieser als request.idempotency_key
enthalten. Überprüfen Sie diesen request
-Hash, wenn Sie die Ursachen für ein Ereignis untersuchen.
Datenobjekt und vorherige Attribute
Für *.updated
-Ereignisse enthält die Ereignisnutzlast data.previous_attributes
, mit denen Sie überprüfen können, was am Stripe-Objekt geändert wurde. Die previous_ attributes
im obigen Beispielereignis customer.subscription.updated
weisen neben weiteren Änderungen darauf hin, dass der vorherige Wert des Abonnements status: trialing
war. Das data.object
gibt den Status als active
an, was bedeutet, dass sich das Abonnement nicht mehr im Testzeitraum befindet.
Ausstehende Übermittlungen
Verwenden Sie pending_webhooks
, um zu ermitteln, wie viele der für dieses Ereignis konfigurierten Endpoints nicht erfolgreich auf die Übermittlung reagiert haben. Bei der ersten Übermittlung ist dieser Wert 1 oder höher, da Ihr Endpoint nicht erfolgreich geantwortet hat. Wenn Sie dieses Ereignis später abrufen, verringern sich pending_webhooks
auf mindestens 0, da jeder Endpoint erfolgreich antwortet. Dies ist wichtig für Ereignisse vom Typ invoice.created
, da fehlgeschlagene Übermittlungen die Finalisierung der Rechnung verzögern können.
Ereignisse von verbundenen Konten
Ereignisse von verbundenen Konten, die an einen Connect-Endpoint übermittelt werden, enthalten den Parameter account
. Verwenden Sie account
, um zu verfolgen, zu welchem verbundenen Konto das Objekt gehört. So kann Ihre Plattform die Ereignisdaten ordnungsgemäß verarbeiten.
Gründe für die Generierung von Ereignisobjekten
Diese Tabelle beschreibt verschiedene Szenarien, die das Generieren von Ereignisobjekten auslösen.
Quelle | Auslöser |
---|---|
Dashboard | Wenn Sie eine API aufrufen, indem Sie Ihre Stripe-Ressourcen im Stripe-Dashboard ändern. |
API | Wenn eine Nutzeraktion in Ihrer App oder auf Ihrer Website zu einem API-Aufruf führt. |
API | Wenn Sie ein Ereignis manuell mit der Stripe-CLI auslösen. |
API | Wenn Sie eine API direkt mit der Stripe-CLI aufrufen. |
Jetzt starten
Um mit dem Empfang von Webhook-Ereignissen in Ihrer App zu beginnen, erstellen und registrieren Sie einen Webhook-Endpoint, indem Sie die folgenden Schritte ausführen:
- Erstellen Sie einen Webhook-Endpoint-Handler, um POST-Anfragen für Ereignisdaten zu empfangen.
- Testen Sie Ihren Webhook-Endpoint-Handler lokal mit der Stripe-CLI.
- Registrieren Sie Ihren Endpoint in Stripe über das Dashboard oder die API.
- Schützen Sie Ihren Webhook-Endpoint.
Sie können einen Endpoint registrieren und erstellen, um mehrere verschiedene Ereignistypen auf einmal zu verarbeiten, oder individuelle Endpoints für bestimmte Ereignisse einrichten.
Einen Handler erstellen
Richten Sie eine HTTP- oder HTTPS-Endpoint-Funktion ein, die Webhook-Anfragen mit einer POST-Methode akzeptieren kann. Wenn Sie noch dabei sind, Ihre Endpoint-Funktion auf Ihrem lokalen Computer zu entwickeln, kann HTTP für diese verwendet werden. Nachdem sie öffentlich zugänglich ist, muss Ihre Webhook-Endpoint-Funktion HTTPS nutzen.
Richten Sie Ihre Endpoint-Funktion so ein, dass sie:
- POST-Anfragen mit einer JSON-Nutzlast verarbeitet, die aus einem Ereignisobjekt besteht.
- Schnell einen erfolgreichen Statuscode (
2xx
) zurückgibt, bevor eine komplexe Logik angewendet wird, die eine Zeitüberschreitung verursachen könnte. Beispielsweise müssen Sie eine200
-Antwort zurückgeben, bevor Sie eine Kundenrechnung in Ihrem Buchhaltungssystem als bezahlt aktualisieren können.
Notiz
Alternativ können Sie mit unserem interaktiven Webhook-Endpoint-Generator eine Webhook-Endpoint-Funktion in Ihrer Programmiersprache erstellen.
Beispiel-Endpoint
Dieser Codeausschnitt ist eine Webhook-Funktion, die so konfiguriert ist, dass sie prüft, ob der Ereignistyp empfangen wurde, das Ereignis verarbeitet und eine 200-Antwort zurückgibt.
Handler testen
Bevor Sie mit Ihrer Webhook-Endpoint-Funktion live gehen, empfehlen wir Ihnen, Ihre Anwendungsintegration zu testen. Konfigurieren Sie dazu einen lokalen Listener zum Senden von Ereignissen an Ihren lokalen Computer und senden Sie Testereignisse. Zum Testen müssen Sie die CLI verwenden.
Ereignisse an einen lokalen Endpoint weiterleiten
Um Ereignisse an Ihren lokalen Endpoint weiterzuleiten, führen Sie den folgenden Befehl mit der CLI aus und richten einen lokalen Listener ein. Das Flag --forward-to
sendet alle Stripe-Ereignisse im Testmodus an Ihren lokalen Webhook-Endpoint.
stripe listen --forward-to localhost:4242/stripe_webhooks
Notiz
Sie können auch den Befehl „stripe listen“ in der Stripe Shell ausführen, um Ereignisse über das Stripe Shell-Datenterminal anzuzeigen. Ereignisse von der Shell können Sie jedoch nicht an Ihren lokalen Endpoint weiterleiten.
Folgende, nützliche Konfigurationen helfen Ihnen beim Testen mit Ihrem lokalen Listener:
- Um die Verifizierung des HTTPS-Zertifikats zu deaktivieren, verwenden Sie das optionale Flag
--skip-verify
. - Um nur bestimmte Ereignisse weiterzuleiten, verwenden Sie das optionale Flag
--events
und übergeben Sie eine durch Kommas getrennte Liste von Ereignissen.
stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \ --forward-to localhost:4242/webhook
- Um Ereignisse von dem öffentlichen Webhook-Endpoint, den Sie bereits bei Stripe registriert haben, an Ihren lokalen Webhook-Endpoint weiterzuleiten, verwenden Sie das optionale Flag
--load-from-webhooks-api
. Es lädt Ihren registrierten Endpoint, analysiert den Pfad und die registrierten Ereignisse und hängt dann den Pfad an Ihren lokalen Webhook-Endpoint im--forward-to path
an.
stripe listen --load-from-webhooks-api --forward-to localhost:5000
- Um Webhook-Signaturen zu überprüfen, verwenden Sie
{{WEBHOOK_SIGNING_SECRET}}
aus der ursprünglichen Ausgabe des Befehls „listen“.
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
Auslösen von Testereignissen
Um Testereignisse zu senden, lösen Sie einen Ereignistyp aus, den Ihr Ereignisziel abonniert hat, indem Sie manuell ein Objekt über das Stripe-Dashboard erstellen. Alternativ können Sie den folgenden Befehl in der Stripe Shell oder Stripe-CLI verwenden.
Dieses Beispiel löst ein payment_intent.succeeded
-Ereignis aus:
stripe trigger payment_intent.succeeded Running fixture for: payment_intent Trigger succeeded! Check dashboard for event details.
Notiz
Erfahren Sie, wie Sie Ereignisse mit Stripe für VS Code auslösen können.
Ihren Endpoint bei Stripe registrieren
Nachdem Sie Ihre Webhook-Endpoint-Funktion getestet haben, registrieren Sie die URL des Webhook-Endpoints im Abschnitt Webhooks im Entwickler-Dashboard oder in der API. Dadurch weiß Stripe, wohin Ereignisse übermittelt werden sollen. Sie können bis zu 16 Webhook-Endpoints bei Stripe registrieren. Registrierte Webhook-Endpoints müssen öffentlich zugängliche HTTPS-URLs sein.
Webhook-URL-Format
Das URL-Format zum Registrieren eines Webhook-Endpoints ist:
https://<your-website>/<your-webhook-endpoint>
Wenn Ihre Domain beispielsweise https://mycompanysite.com
ist und die Route zu Ihrem Webhook-Endpoint @app.route('/stripe_webhooks', methods=['POST'])
lautet, geben Sie https://mycompanysite.com/stripe_webhooks
als Endpoint-URL an.
Webhook-Endpoint hinzufügen
Notiz
Wenn Sie Workbench in Ihrem Konto aktiviert haben, müssen Sie Workbench verwenden, um Ihren Webhook-Endpoint zu registrieren.
Stripe unterstützt zwei Arten von Endpoints: Account und Connect. Erstellen Sie einen Endpoint für Account, es sei denn, Sie haben bereits eine Connect-Anwendung entwickelt. Führen Sie folgende Schritte aus, um einen Webhook-Endpoint im Entwickler-Dashboard zu registrieren. Sie können bis zu 16 Webhook-Endpoints pro Stripe-Konto registrieren.
- Navigieren Sie zur Seite Webhooks.
- Klicken Sie auf Endpoint hinzufügen.
- Fügen Sie die HTTPS-URL Ihres Webhook-Endpoints in Endpoint-URL ein.
- Wenn Sie über ein Konto bei Stripe Connect verfügen, geben Sie eine Beschreibung ein und klicken Sie dann auf Ereignisse von verbundenen Konten überwachen.
- Wählen Sie unter Ereignisse auswählen die Ereignistypen aus, die Sie zurzeit in Ihrem lokalen Webhook-Endpoint empfangen.
- Klicken Sie auf Endpoint hinzufügen.
Einen Webhook-Endpoint bei der Stripe API registrieren
Sie können Webhook-Endpoints auch programmgesteuert erstellen.
Um Ereignisse von verbundenen Konten zu empfangen, verwenden Sie den Connect-Parameter.
Das folgende Beispiel erstellt einen Endpoint, der Sie darüber informiert, ob Zahlungen erfolgreich sind oder fehlschlagen.
Webhook-Endpoint schützen
Wir empfehlen Ihnen dringend, Ihre Integration zu schützen. Ihr Handler sollte deshalb prüfen, dass alle Webhook-Anfragen tatsächlich von Stripe generiert werden. Sie können Webhook-Signaturen mithilfe unserer offiziellen Bibliotheken oder manuell verifizieren.
Webhook-Integrationen debuggen
Bei der Übermittlung von Ereignissen an Ihren Webhook-Endpoint können mehrere Arten von Problemen auftreten:
- Stripe kann ein Ereignis möglicherweise nicht an Ihren Webhook-Endpoint übermitteln.
- Bei Ihrem Webhook-Endpoint besteht möglicherweise ein SSL-Problem.
- Ihre Netzwerkverbindung wurde unterbrochen.
- Ihr Webhook-Endpoint empfängt die von Ihnen erwarteten Ereignisse nicht.
Ereignisübermittlungen anzeigen
Notiz
Wenn Sie Workbench in Ihrem Konto aktiviert haben, müssen Sie Workbench verwenden, um Ihre Ereignisübermittlungen zu verwalten.
Um Ereignisübermittlungen für einen bestimmten Endpoint anzuzeigen, wählen Sie den Webhook-Endpoint auf der Registerkarte Webhooks aus.
Um alle Ereignisse anzuzeigen, die in Ihrem Konto ausgelöst wurden, rufen Sie die Registerkarte Ereignisse auf.
HTTP-Statuscodes korrigieren
Wenn ein Ereignis den Statuscode 200
anzeigt, bedeutet dies eine erfolgreiche Übermittlung an den Webhook-Endpoint. Möglicherweise erhalten Sie auch einen anderen Statuscode als 200
. In der folgenden Tabelle finden Sie eine Liste gängiger HTTP-Statuscodes und empfohlener Lösungen.
Webhook-Status ausstehend | Beschreibung | Lösung |
---|---|---|
(Verbindung nicht möglich) FHLR | Wir können keine Verbindung zum Zielserver herstellen. | Stellen Sie sicher, dass Ihre Host-Domain im Internet öffentlich zugänglich ist. |
(302 ) FHLR (oder ein anderer 3xx -Status) | Der Zielserver hat versucht, die Anfrage an einen anderen Standort umzuleiten. Wir betrachten Weiterleitungsantworten auf Webhook-Anfragen als fehlgeschlagen. | Legen Sie das Webhook-Endpoint-Ziel auf die durch die Weiterleitung aufgelöste URL fest. |
(400 ) FHLR (oder ein anderer 4xx -Status) | Der Zielserver kann oder wird die Anfrage nicht verarbeiten. Dies kann vorkommen, wenn der Server einen Fehler erkennt (400 ), wenn für die Ziel-URL Zugriffsbeschränkungen gelten (401 , 403 ) oder wenn die Ziel-URL nicht existiert (404 ). |
|
(500 ) FHLR (oder ein anderer 5xx -Status) | Bei der Verarbeitung der Anfrage auf dem Zielserver ist ein Fehler aufgetreten. | Überprüfen Sie die Logs Ihrer Anwendung, um zu verstehen, warum ein 500 -Fehler zurückgegeben wird. |
(TLS-Fehler) FHLR | Es konnte keine sichere Verbindung zum Zielserver hergestellt werden. Diese Fehler werden in der Regel durch ein Problem mit dem SSL/TLS-Zertifikat oder einem Zwischenzertifikat in der Zertifikatskette des Zielservers verursacht. | Führen Sie einen SSL-Servertest durch, um die mögliche Ursache dieses Fehlers zu finden. |
(Zeitüberschreitung) FHLR | Die Antwort des Zielservers auf die Webhook-Anfrage dauerte zu lange. | Stellen Sie sicher, dass Sie komplexe Logik zurückstellen und sofort eine erfolgreiche Antwort in Ihrem Webhook-Verarbeitungscode zurückgeben. |
Verhaltensweisen der Ereignisübermittlung
In diesem Abschnitt erfahren Sie, welche Verhaltensweisen Sie in Bezug auf das Senden von Ereignissen durch Stripe an Ihren Webhook-Endpoint erwarten können.
Wiederholungsverhalten
Im Live-Modus versucht Stripe bis zu drei Tage lang, ein bestimmtes Ereignis mit einem exponentiellen Backoff an Ihren Webhook-Endpoint zu übermitteln. Im Abschnitt Ereignisse des Dashboards können Sie anzeigen, wann der nächste Wiederholungsversuch stattfindet.
Im Test-Modus wiederholt Stripe die Übermittlung dreimal innerhalb weniger Stunden. Sie können die Übermittlung einzelner Ereignisse an Ihren Webhook-Endpoint nach dieser Zeit manuell über die Registerkarte Ereignisse des Dashboards wiederholen. Sie können auch verpasste Ereignisse abfragen, um die Daten über einen beliebigen Zeitraum abzugleichen.
Die automatischen Wiederholungsversuche werden auch dann fortgesetzt, wenn Sie versuchen, einzelne Webhook-Ereignisse manuell an einen bestimmten Endpoint zu übertragen, und der Versuch erfolgreich ist.
Wenn Ihr Endpoint bei unserem Wiederholungsversuch von Stripe deaktiviert oder gelöscht wurde, werden keine zukünftigen Wiederholungsversuche für dieses Ereignis unternommen. Wenn Sie einen Webhook-Endpoint jedoch deaktivieren und wieder reaktivieren, bevor Stripe einen erneuten Versuch unternehmen kann, können Sie nach wie vor zukünftige Wiederholungsversuche erwarten.
Verhalten deaktivieren
Im Live- und Test-Modus versucht Stripe, Sie per E-Mail über einen falsch konfigurierten Endpoint zu benachrichtigen, wenn der Endpoint mehrere Tage hintereinander nicht mit dem HTTP-Statuscode 2xx
geantwortet hat. In der E-Mail wird auch angegeben, wann der Endpoint automatisch deaktiviert wird.
API-Versionierung
Die API-Version in Ihren Kontoeinstellungen beim Auftreten des Ereignisses bestimmt die API-Version und damit die Struktur eines Event
-Objekts, das in einem Webhook gesendet wird. Wenn für Ihr Konto beispielsweise eine ältere API-Version festgelegt ist, z. B. 2015-02-16, und Sie die API-Version für eine bestimmte Anfrage mit Versionierung ändern, basiert das generierte und an Ihren Endpoint gesendete Event
-Objekt weiterhin auf der API-Version 2015-02-16.
Sie können Event
-Objekte nach Erstellung nicht mehr ändern. Wenn Sie beispielsweise eine Zahlung aktualisieren, bleibt das ursprüngliche Zahlungsereignis unverändert. Das bedeutet, dass nachfolgende Aktualisierungen der API-Version Ihres Kontos vorhandene Event
-Objekte nicht rückwirkend ändern. Auch das Abrufen älterer Ereignisse durch Aufrufen von /v1/events
mithilfe einer neueren API-Version wirkt sich nicht auf die Struktur der empfangenen Ereignisse aus.
Sie können Test-Webhook-Endpoints entweder für Ihre Standard-API-Version oder die neueste API-Version festlegen. Das an die Webhook-URL gesendete Event
ist speziell für die angegebene Version des Endpoints strukturiert. Sie können auch programmgesteuert mit einer bestimmen api_version Endpoints erstellen.
Anordnung von Ereignissen
Stripe bietet keine Garantie für die Übermittlung von Ereignissen in der Reihenfolge, in der sie generiert wurden. Beim Erstellen eines Abonnements können beispielsweise die folgenden Ereignisse generiert werden:
customer.subscription.created
invoice.created
invoice.paid
charge.created
(wenn eine Zahlung vorhanden ist)
Ihr Endpoint sollte nicht mit der Übermittlung dieser Ereignisse in dieser Reihenfolge rechnen und muss die Übermittlung entsprechend handhaben. Sie können die API auch verwenden, um fehlende Objekte abzurufen (zum Beispiel können Sie die Rechnungs-, Zahlungs- und Abonnementobjekte mithilfe der Informationen aus invoice.paid
abrufen, wenn Sie dieses Ereignis zuerst erhalten).
Best Practices für die Verwendung von Webhooks
Überprüfen Sie diese Best Practices, um sicherzustellen, dass Ihre Webhooks sicher bleiben und gut mit Ihrer Integration funktionieren.
Umgang mit doppelten Ereignissen
Webhook-Endpoints empfangen gelegentlich dasselbe Ereignis mehrmals. Sie können sich vor dem Erhalt doppelter Ereignisse schützen, indem Sie Ihre Ereignisse idempotent verarbeiten. Eine Möglichkeit, dies zu tun, besteht darin, die von Ihnen verarbeiteten Ereignisse zu protokollieren und dann bereits protokollierte Ereignisse nicht zu verarbeiten.
Überwachen Sie nur Ereignistypen, die für Ihre Integration erforderlich sind
Konfigurieren Sie Ihre Webhook-Endpoints so, dass sie nur die für Ihre Integration erforderlichen Ereignistypen empfangen. Die Überwachung zusätzlicher Ereignisse (oder aller Ereignisse) belastet Ihren Server und wird nicht empfohlen.
Sie können die Ereignisse, die ein Webhook-Endpoint empfängt, im Dashboard oder über die API ändern.
Ereignisse asynchron verarbeiten
Konfigurieren Sie Ihren Handler so, dass dieser eingehende Ereignisse in einer asynchronen Warteschlange verarbeitet. Wenn Sie Ereignisse synchron verarbeiten, kann es zu Skalierbarkeitsproblem kommen. Ein starker Anstieg der Webhook-Übermittlungen (z. B. zu Beginn des Monats, wenn alle Abonnements verlängert werden) kann Ihre Endpoint-Hosts überfordern.
Mit asynchronen Warteschlangen können Sie simultan laufende Ereignisse mit einer Geschwindigkeit verarbeiten, die zu Ihrem System passt.
Webhook-Route nicht mit dem CSRF-Schutz absichern
Wenn Sie Rails, Django oder ein anderes Web-Framework verwenden, überprüft Ihre Website möglicherweise automatisch, ob jede POST-Anfrage ein CSRF-Token enthält. Dies ist eine wichtige Sicherheitsfunktion, die Sie und Ihre Nutzer/innen vor Cross-Site-Request-Forgery -Angriffen schützt. Diese Sicherheitsmaßnahme kann Ihre Website jedoch auch daran hindern, legitime Ereignisse zu verarbeiten. In diesem Fall müssen Sie möglicherweise die Webhooks-Route vom CSRF-Schutz ausnehmen.
Ereignisse mit einem HTTPS-Server empfangen
Wenn Sie eine HTTPS-URL für Ihren Webhook-Endpoint verwenden, validiert Stripe, dass die Verbindung zu Ihrem Server sicher ist, bevor wir Ihre Webhook-Daten senden. Damit dies funktioniert, muss der Server so konfiguriert sein, dass er HTTPS mit einem gültigen Serverzertifikat unterstützt. HTTPS-URLs sind im Live-Modus erforderlich. TLS v1.3. wird derzeit von Stripe-Webhooks nicht unterstützt.
Geheimschlüssel für Signaturen für Endpoints in regelmäßigen Abständen neu generieren
Der Geheimschlüssel, mit dem verifiziert wird, das Ereignisse von Stripe stammen kann im Webhooks-Abschnitt des Dashboards geändert werden. Klicken Sie für jeden Endpoint auf Geheimschlüssel neu generieren. Sie können den aktuellen Geheimschlüssel sofort ablaufen lassen oder den Ablauf um bis zu 24 Stunden verzögern, damit Sie Zeit haben, den Verifizierungscode auf Ihrem Server zu aktualisieren. Während dieses Zeitraums sind mehrere Geheimschlüssel für den Endpoint aktiv. Stripe generiert bis zum Ablauf eine Signatur pro Geheimschlüssel. Um diese zu schützen, empfehlen wir, Geheimschlüssel in regelmäßigen Abständen neu zu generieren oder spätestens wenn Sie vermuten, dass ein Geheimschlüssel kompromittiert wurde.
Überprüfen, ob Ereignisse von Stripe gesendet werden
Stripe sendet Webhook-Ereignisse von einer festgelegten Liste von IP-Adressen. Vertrauen Sie nur Ereignissen, die von diesen IP-Adressen stammen.
Überprüfen Sie außerdem die Webhook-Signaturen, um zu bestätigen, dass die empfangenen Ereignisse von Stripe gesendet werden. Stripe signiert Webhook-Ereignisse, die an Ihre Endpoints gesendet werden, indem eine Signatur in den Stripe-Signature
-Header jedes Ereignisses eingefügt wird. So können Sie überprüfen, ob die Ereignisse von Stripe und nicht von einem Drittanbieter gesendet wurden. Sie können Signaturen entweder mit unseren offiziellen Bibliotheken verifizieren oder mit Ihrer eigenen Lösung manuell verifizieren.
Im folgenden Abschnitt wird beschrieben, wie Sie Webhook-Signaturen prüfen:
- Rufen Sie den Geheimschlüssel Ihres Endpoints ab.
- Überprüfen Sie die Signatur.
Geheimschlüssel Ihres Endpoints abrufen
Verwenden Sie den Abschnitt Webhooks des Dashboards. Wählen Sie einen Endpoint aus, für den Sie den Geheimschlüssel abrufen möchten, und suchen Sie oben rechts auf der Seite nach dem Geheimschlüssel.
Stripe generiert für jeden Endpoint einen eindeutigen Geheimschlüssel. Wenn Sie denselben Endpoint sowohl für Test- als auch für Live-API-Schlüssel verwenden, ist der Geheimschlüssel für jeden dieser Schlüssel unterschiedlich. Wenn Sie mehrere Endpoints verwenden, müssen Sie außerdem für jeden Endpoint, für den Sie Signaturen verifizieren möchten, einen Geheimschlüssel abrufen. Stripe beginnt dann damit, jeden Webhook zu signieren, der an den Endpoint gesendet wird.
Replay-Angriffe verhindern
Bei einem Replay-Angriff fängt ein Angreifer eine gültige Nutzlast und deren Signatur ab und überträgt sie dann erneut. Um solche Angriffe zu verhindern, fügt Stripe einen Zeitstempel in den Stripe-Signature
-Header ein. Da der Zeitstempel zu der signierten Nutzlast gehört, ist er ebenfalls durch die Signatur verifiziert. So kann ein Angreifer den Zeitstempel nicht ändern, ohne dass die Signatur ungültig wird. Wenn die Signatur gültig, der Zeitstempel aber zu alt ist, kann Ihre Anwendung die Nutzlast ablehnen.
Unsere Bibliotheken haben eine Standardtoleranz von 5 Minuten zwischen dem Zeitstempel und der aktuellen Zeit. Sie können diese Toleranz ändern, indem Sie bei der Überprüfung von Signaturen einen zusätzlichen Parameter angeben. Verwenden Sie das Network Time Protocol (NTP), um sicherzustellen, dass die Uhrzeit Ihres Servers korrekt ist und mit der Zeit auf den Servern von Stripe synchronisiert wird.
Stripe generiert den Zeitstempel und die Signatur jedes Mal, wenn wir ein Ereignis an Ihren Endpoint senden. Wenn Stripe ein Ereignis wiederholt (zum Beispiel weil Ihr Endpoint zuvor mit einem Nicht-2xx
-Statuscode geantwortet hat), generieren wir eine neue Signatur und einen neuen Zeitstempel für den neuen Übermittlungsversuch.
„2xx-Antwort“ schnell zurückgeben
Ihr Endpoint muss schnell einen erfolgreichen Statuscode (2xx
) zurückgeben, bevor eine komplexe Logik angewendet wird, die eine Zeitüberschreitung verursachen könnte. Beispielsweise müssen Sie eine 200
-Antwort zurückgeben, bevor Sie eine Kundenrechnung in Ihrem Buchhaltungssystem als bezahlt aktualisieren können.