Stripe-Ereignisse in Ihrem Webhook-Endpoint empfangen

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.

Erstellen Sie ein Ereignisziel, um Ereignisse an einem HTTPS-Webhook-Endpoint zu empfangen. Nach der Registrierung eines Webhook-Endpoints 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.

Sie können mit Ereigniszielen auch Ereignisse in Amazon EventBridge empfangen.

Jetzt starten

Um Webhook-Ereignisse in Ihrer App zu empfangen, erstellen und registrieren Sie einen Webhook-Endpoint:

1. Erstellen Sie einen Webhook-Endpoint-Handler, um POST-Anfragen für Ereignisdaten zu empfangen.
2. Testen Sie Ihren Webhook-Endpoint-Handler lokal mit der Stripe-CLI.
3. Registrieren Sie Ihren Endpoint in Stripe über das Dashboard oder die API.
4. 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.

require 'json'

# Using Sinatra
post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # Then define and call a method to handle the successful payment intent.
    # handle_payment_intent_succeeded(payment_intent)
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    # Then define and call a method to handle the successful attachment of a PaymentMethod.
    # handle_payment_method_attached(payment_method)
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

stripe listen --forward-to localhost:4242/webhook

stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \
  --forward-to localhost:4242/webhook

stripe listen --load-from-webhooks-api --forward-to localhost:4242/webhook

Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)

stripe trigger payment_intent.succeeded
Running fixture for: payment_intent
Trigger succeeded! Check dashboard for event details.

Ihren Endpoint 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.

Neuen Webhook-Endpoint erstellen

You can create new event destinations for webhook and AWS EventBridge destinations.

1. Open the Event destinations tab in Workbench.
2. Click Create new destination.
3. Select the API version for the events object you want to consume.
4. If you’re using Connect, you can listen for Events on connected accounts. Otherwise, choose Events on your account.
5. Select the event types that you want to send to the destination, then click Continue.
6. Select Webhook to send events to an HTTPS endpoint.
7. Provide the Endpoint URL for Stripe to send webhooks to and an optional description for the endpoint.
8. Click Create destination to create your webhook endpoint.

Notiz

Workbench ersetzt das bestehende Entwickler-Dashboard. Wenn Sie immer noch das Entwickler-Dashboard verwenden, finden Sie hier weitere Informationen zum Erstellen eines neuen Webhook-Endpoints.

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 Verbindungsparameter.

Das folgende Beispiel erstellt einen Endpoint, der Sie darüber informiert, ob Zahlungen erfolgreich sind oder fehlschlagen.

Command Line

curl

curl https://api.stripe.com/v1/webhook_endpoints \
  -u 
sk_test_4eC39HqLyjWDarjtT1zdp7dc
: \
  -d "url"="https://example.com/my/webhook/endpoint" \
  -d "enabled_events[]"="payment_intent.payment_failed" \
  -d "enabled_events[]"="payment_intent.succeeded"

# Set your secret key. Remember to switch to your live secret key in production.
# See your keys here: https://dashboard.stripe.com/apikeys
Stripe.api_key = 
'sk_test_4eC39HqLyjWDarjtT1zdp7dc'

require 'stripe'
require 'sinatra'

# If you are testing your webhook locally with the Stripe CLI you
# can find the endpoint's secret by running `stripe listen`
# Otherwise, find your endpoint's secret in your webhook settings in
# the Developer Dashboard
endpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

post '/my/webhook/url' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload
    puts "Error parsing payload: #{e.message}"
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    puts "Error verifying webhook signature: #{e.message}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    puts 'PaymentIntent was successful!'
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    puts 'PaymentMethod was attached to a Customer!'
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end

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

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.

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 verarbeiteten Ereignis-IDs protokollieren und bereits protokollierte Ereignisse dann nicht erneut verarbeiten.

In einigen Fällen werden zwei separate Ereignisobjekte generiert und gesendet. Um diese Duplikate zu identifizieren, verwenden Sie die ID des Objekts in data.object zusammen mit dem event.type.

Ü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 mit der API ändern.

Ereignisse asynchron handhaben

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.

class StripeController < ApplicationController
  # If your controller accepts requests other than Stripe webhooks,
  # you'll probably want to use `protect_from_forgery` to add CSRF
  # protection for your application. But don't forget to exempt
  # your webhook route!
  protect_from_forgery except: :webhook

  def webhook
    # Process webhook data in `params`
  end
end

Ereignisse mit einem HTTPS-Server empfangen

Wenn Sie eine HTTPS-URL für Ihren Webhook-Endpoint verwenden (im Live-Modus erforderlich), 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 Server-Zertifikat unterstützt. Stripe-Webhooks unterstützen nur die TLS-Versionen v1.2 und v1.3.

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:

1. Rufen Sie den Geheimschlüssel Ihres Endpoints ab.
2. Ü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.