Registrieren Sie Stripe-Ereignisse in Ihrem Webhook-Endpoint

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 hilft Ihnen, auf asynchrone Ereignisse zu reagieren, z. B. wenn die Bank eines Kunden/einer Kundin eine Zahlung bestätigt, ein Kunde/eine Kundin eine Zahlung anficht oder wenn eine wiederkehrende Zahlung erfolgreich ist.

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

Loslegen

So empfangen Sie Webhook-Ereignisse in Ihrer App:

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. Erstellen Sie ein neues Ereignisziel für Ihren Webhook-Endpoint.
4. Sichern 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.

Nicht unterstütztes Ereignistypverhalten für Organisationsereignisziele

Stripe sendet die meisten Ereignistypen asynchron. Für bestimmte Ereignistypen wartet Stripe jedoch auf eine Antwort. Das Vorhandensein oder Nichtvorhandensein einer Antwort vom Ereignisziel wirkt sich direkt darauf aus, wie Stripe mit diesen bestimmten Ereignistypen umgeht.

Organisations-Ziele bieten eingeschränkte Unterstützung für Ereignistypen, die eine Antwort erfordern:

• Sie können issuing_authorization.request für Organisationsziele nicht abonnieren. Richten Sie stattdessen einen Webhook-Endpoint in einem Stripe-Konto innerhalb der Organisation ein, um diesen Ereignistyp zu abonnieren. Verwenden Sie issuing_authorization.request, um Kaufanfragen in Echtzeit zu autorisieren.
• Sie können checkout_sessions.completed für Organisationsziele abonnieren. Dadurch wird jedoch kein Weiterleitungsverhalten verarbeitet, wenn Sie Checkout direkt in Ihre Website einbetten oder Kundinnen/Kunden auf eine von Stripe gehostete Bezahlseite weiterleiten. Die Übermittlung eines checkout_sessions.completed-Ereignisses an eine Organisation wirkt sich nicht auf das Weiterleitungsverhalten aus. Um das Checkout-Weiterleitungsverhalten zu beeinflussen, verarbeiten Sie diesen Ereignistyp mit einem Webhook-Endpoint, der in einem Stripe-Konto innerhalb der Organisation konfiguriert ist.
• Sie können invoice.created für Organisationsziele abonnieren. Wenn Sie nicht erfolgreich auf dieses Ereignis reagieren, hat dies keinen Einfluss auf die automatische Rechnungsfinalisierung bei Verwendung des automatischen Einzugs. Um die automatische Rechnungsfinalisierung über Webhook-Endpoint-Antworten zu beeinflussen, verarbeiten Sie diesen Ereignistyp mit einem Webhook-Endpoint, der in einem Stripe Konto innerhalb der Organisation konfiguriert ist.

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

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

  # Extract the context
  context = event.context

  # Define your API key variables (ideally loaded securely)
  ACCOUNT_123_API_KEY = "sk_test_123"
  ACCOUNT_456_API_KEY = "sk_test_456"

  account_api_keys = {
    "account_123" => ACCOUNT_123_API_KEY,
    "account_456" => ACCOUNT_456_API_KEY
  }

  api_key = account_api_keys[context]

  if api_key.nil?
    puts "No API key found for context: #{context}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'customer.created'
    customer = event.data.object

    begin
      latest_customer = Stripe::Customer.retrieve(
        customer.id,
        { api_key: api_key }
      )
      handle_customer_created(latest_customer, context)
    rescue => e
      puts "Error retrieving customer: #{e.message}"
      status 500
      return
    end

  when 'payment_method.attached'
    payment_method = event.data.object

    begin
      latest_payment_method = Stripe::PaymentMethod.retrieve(
        payment_method.id,
        { api_key: api_key }
      )
      handle_payment_method_attached(latest_payment_method, context)
    rescue => e
      puts "Error retrieving payment method: #{e.message}"
      status 500
      return
    end

  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, verwenden Sie die API oder die Registerkarte Webhooks in Workbench zum Registrieren der URL Ihres Webhook-Endpoints, um sicherzustellen, dass weiß, wohin Ereignisse gesendet 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.

Ein Ereignisziel für Ihren Webhook-Endpoint erstellen

Erstellen Sie ein Ereignisziel mit Workbench im Dashboard oder programmgesteuert mit der API. Sie können bis zu 16 Ereignisziele für jedes Stripe-Konto registrieren.

Dashboard

API

So erstellen Sie einen neuen Webhook-Endpoint im Dashboard:

1. Öffnen Sie die Registerkarte Webhooks in Workbench.
2. Klicken Sie auf Ereignisziel erstellen.
3. Wählen Sie aus, von wo Sie Ereignisse empfangen möchten. Stripe unterstützt zwei Arten von Konfigurationen: Ihr Konto und Verbundene Konten. Wählen Sie Konto aus, um Ereignisse von Ihrem eigenen Konto aus zu überwachen. Wenn Sie eine Connect-Anwendung erstellt haben und Ereignisse von Ihren verbundenen Konten überwachen möchten, wählen Sie Verbundene Konten aus.

Ereignisse von einem Organisations-Webhook-Endpoint überwachen

Wenn Sie einen Webhook-Endpoint in einem Organisationskonto erstellen, wählen Sie Konten aus, um Ereignisse von Konten in Ihrer Organisation zu überwachen. Wenn Ihre Organisationen Connect-Plattformen als Mitglieder haben und Ereignisse von allen verbundenen Konten der Plattformen überwachen möchten, wählen Sie Verbundene Konten aus.

1. Wählen Sie die API-Version für das Ereignisobjekt aus, das Sie verwenden möchten.
2. Wählen Sie die Ereignistypen aus, die Sie an einen Webhook-Endpoint senden möchten.
3. Wählen Sie Weiter und dann Webhook-Endpoint als Zieltyp aus.
4. Klicken Sie auf Weiter und geben Sie dann die Endpoint-URL und eine optionale Beschreibung für den Webhook ein.

Einen neuen Webhook über die Registerkarte Webhooks registrieren

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.

# 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_BQokikJOvBiI2HlWgH4olfQ2'

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 ist unterbrochen.
• Ihr Webhook-Endpoint empfängt die von Ihnen erwarteten Ereignisse nicht.

Ereignisübermittlungen anzeigen

Um Ereignisübermittlungen anzuzeigen, wählen Sie den Webhook-Endpoint unter Webhooks und dann die Registerkarte Ereignisse aus.

The Events tab provides a list of events and whether they’re Delivered, Pending, or Failed. Click an event to view metadata, including the HTTP status code of the delivery attempt and the time of pending future deliveries.

HTTP-Statuscodes korrigieren

Wenn ein Ereignis den Statuscode 200 anzeigt, bedeutet dies eine erfolgreiche Zustellung 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.

Automatische Wiederholungsversuche

Stripe versucht, Ereignisse mit einem exponentiellen Backoff im Live-Modus bis zu drei Tage an Ihr Ziel zu senden. Wann der nächste Wiederholungsversuch stattfinden wird, sofern zutreffend, sehen Sie auf der Registerkarte Ereignisübermittlungen Ihres Ereignisziels. Wir versuchen, Ereignisse, die in einer Sandbox erstellt wurde, innerhalb weniger Stunden dreimal zu übermitteln. Wenn Ihr Ziel bei unserem Wiederholungsversuch deaktiviert oder gelöscht wurde, unternehmen wir keine zukünftigen Wiederholungsversuche für dieses Ereignis. Wenn Sie ein Ereignisziel jedoch deaktivieren und wieder reaktivieren, bevor wir einen erneuten Versuch starten können, sehen Sie nach wie vor zukünftige Wiederholungsversuche.

Manuelle Wiederholungsversuche

There are two ways to manually retry events:

• In the Stripe Dashboard, click Resend when looking at a specific event. This works for up to 15 days after the event creation.
• With the Stripe CLI, run the stripe events resend <event_id> --webhook-endpoint=<endpoint_id> command. This works for up to 30 days after the event creation.

Anordnung von Ereignissen

Stripe garantiert die Übermittlung von Ereignissen nicht 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)

Stellen Sie sicher, dass Ihr Ereignisziel Ereignisse nicht nur in einer bestimmten Reihenfolge empfangen kann. Ihr Ziel sollte jegliche Übermittlung entsprechend verarbeiten können. Sie können fehlende Objekte auch mit der API abrufen. So können Sie beispielsweise die Objekte für Rechnung, Zahlung und Abonnement mit den Informationen aus invoice.paid abrufen, wenn Sie dieses Ereignis zuerst erhalten.

API-Versionierung

The API version in your account settings when the event occurs dictates the API version, and therefore the structure of an Event sent to your destination. For example, if your account is set to an older API version, such as 2015-02-16, and you change the API version for a specific request with versioning, the Event object generated and sent to your destination is still based on the 2015-02-16 API version. You can’t change Event objects after creation. For example, if you update a charge, the original charge event remains unchanged. As a result, subsequent updates to your account’s API version don’t retroactively alter existing Event objects. Retrieving an older Event by calling /v1/events using a newer API version also has no impact on the structure of the received event. You can set test event destinations to either your default API version or the latest API version. The Event sent to the destination is structured for the event destination’s specified version.

Best Practices für die Verwendung von Webhooks

Überprüfen Sie diese Best Practices, um sicherzustellen, dass Ihre Webhook-Endpoints 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.

Nur die Ereignistypen überwachen, die Ihre Integration erfordert

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 verarbeiten

Konfigurieren Sie Ihren Handler so, dass eingehende Ereignisse mit einer asynchronen Warteschlange verarbeitet werden. Möglicherweise treten Skalierbarkeitsprobleme auf, wenn Sie sich für die synchrone Verarbeitung von Ereignissen entscheiden. Jeder große Anstieg bei den Webhook-Übermittlungen (z. B. zu Beginn des Monats, wenn alle Abonnements verlängert werden) kann Ihre Endpoint-Hosts überfordern.

Asynchrone Warteschlangen ermöglichen es Ihnen, die gleichzeitigen Ereignisse mit einer Geschwindigkeit zu verarbeiten, die Ihr System unterstützen kann.

Webhook-Route vom CSRF-Schutz ausgenommen

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, der verwendet wird, um zu überprüfen, ob Ereignisse von Stripe stammen, kann auf der Registerkarte Webhooks in Workbench geändert werden. Um Geheimschlüssel zu schützen, empfehlen wir sie in regelmäßigen Abständen neu zu generieren (zu ändern) oder wenn Sie vermuten, dass ein Geheimschlüssel kompromittiert wurde.

So generieren Sie einen Geheimschlüssel neu:

1. Klicken Sie auf die einzelnen Endpoints auf der Workbench-Registerkarte Webhooks, für die Sie den Geheimschlüssel neu generieren möchten.
2. Navigieren Sie zum Überlaufmenü () und klicken Sie 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.

Ü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 auch Webhook-Signaturen, um zu bestätigen, dass Stripe die empfangenen Ereignisse gesendet hat. 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 verifizieren:

1. Rufen Sie den Geheimschlüssel Ihres Endpoints ab.
2. Überprüfen Sie die Signatur.

Geheimschlüssel Ihres Endpoints abrufen

Verwenden Sie Workbench und navigieren Sie zur Registerkarte Webhooks, um Ihre sämtlichen Endpoints anzuzeigen. Wählen Sie einen Endpoint aus, für den Sie den Geheimschlüssel abrufen möchten, und klicken Sie dann auf Zum Einblenden klicken.

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. Nach dieser Einrichtung beginnt Stripe, 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 Zustellungsversuch.

Schnelle Rückgabe einer 2xx-Antwort

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.