Integration mit Ereignissen

Senden Sie Ereignisse von Stripe an Webhook-Endpoints und Cloud-Dienste.

Richten Sie ein Ereignisziel ein, um Ereignisse von Stripe für mehrere Zieltypen zu empfangen, einschließlich Webhook-Endpoints und Amazon EventBridge.

Darüber hinaus können Sie Thin-Ereignisse verwenden, die von API v2-Endpoints erstellt wurden. Die SDKs für API v2 enthalten Helper, die es Ihrer Anwendung ermöglichen, den neuesten Objektstatus von Stripe abzurufen.

Anwendungsfälle

Wenn Sie Stripe-Integrationen erstellen, möchten Sie möglicherweise, dass Ihre Anwendungen Ereignisse in Echtzeit von Ihren Stripe-Konten empfangen, sodass Ihre Backend-Systeme entsprechend Aktionen ausführen und darauf reagieren können.

Mit einem Ereignisziel überträgt Stripe Echtzeit-Ereignisdaten von Ihrem Konto, sodass Sie Back-End-Aktionen ausführen können, zum Beispiel:

Nutzer/innen eine Benachrichtigung senden, wenn der Kunde/die Kundin eine Zahlung bestätigt
Interne Anspruchsprüfung einleiten, wenn eine Kundin/ein Kunde eine Zahlung angefochten hat
Ihren Nutzer/innen Zugriff gewähren, wenn sie erfolgreiche wiederkehrende Abonnementzahlungen tätigen

Unterstützte Zieltypen

Ereignisse mit Amazon EventBridge an ein AWS-Konto senden oder über Webhook-Endpoints an einen HTTPS-Endpunkt übermitteln.

Ereignis-Übersicht

Stripe generiert Ereignisdaten, um Sie über die Aktivitäten in Ihrem Konto auf dem Laufenden zu halten.

Wenn ein Ereignis eintritt, generiert Stripe ein neues Event-Objekt. Nachdem Ihr Ziel das Event empfangen hat, kann Ihre App Back-End-Aktionen ausführen (zum Beispiel indem die APIs Ihres Versanddienstleisters aufgerufen werden, um eine Sendung zu planen, nachdem Sie das Ereignis payment_intent.succeeded erhalten haben). Wir stellen zwei verschiedene Arten von Event-Objekten zur Verfügung:

Thin-Ereignisse: Diese Ereignisse enthalten nur die IDs der betroffenen Objekte. Sie werden von API v2 endpoints generiert. API v1 endpoints generiert ebenfalls Thin-Ereignisse. Hier finden Sie eine vollständige Liste der Thin-Ereignisse.
Snapshot-Ereignisse: Diese Ereignisse bieten eine letztendlich konsistente Momentaufnahme des Objekts, das geändert wurde, und werden nur von API v1 endpoints generiert. Sie können die Eigenschaft previous_attributes enthalten, die die ggf. vorhandene Änderung angibt. Hier finden Sie eine vollständige Liste der Snapshot-Ereignisse.

Diese Tabelle gibt einen Überblick über die allgemeinen Unterschiede zwischen Thin-Ereignissen und Snapshot-Ereignissen.

Charaktereigenschaften	Snapshot-Ereignisse	Thin-Ereignisse
Erstellt von	API v1 Änderungen am Ressourcen-Status	API v2 Änderungen am Ressourcen-Status
Payload	Groß: Enthält einen Snapshot des API-Objekts, das sich auf das Ereignis bezieht	Klein: Enthält nur eine ID des API-Objekts, das sich auf das Ereignis bezieht
Greifen Sie auf zusätzliche Daten zu, um das Ereignis zu verarbeiten.	Rufen Sie die neueste Objektdefinition von der API ab. Die Objektdefinition in der Ereignisnutzlast kann zum Zeitpunkt der Verarbeitung des Ereignisses bereits veraltet sein.	Rufen Sie das neueste Objekt von der API oder das vollständige Ereignis von `v2/events` ab. Die vollständige Ereignisnutzlast kann zusätzliche Details über das Ereignis enthalten. Beispielsweise enthält die Nutzlast für ein `v1.billing.meter.error_report_triggered`-Ereignis Informationen über die Art und Häufigkeit der ausgelösten Fehler.
SDK-Typisierung	Nicht typisiert	Typisiert
Versionierung	Versioniert nach API-Version	Nicht versioniert, sodass Sie Ihre Integration aktualisieren können, ohne die Konfiguration Ihrer Webhook-Endpoints ändern zu müssen

Eine einzelne API-Anfrage kann zur Erstellung mehrerer Ereignisse führen. Wenn Sie beispielsweise ein neues Abonnement für einen Kunden/eine Kundin erstellen, kann dies zu den Ereignissen customer.subscription.created und payment_intent.succeeded führen. Wählen Sie die Ereignisse aus, die Sie für jedes Ereignisziel abonnieren möchten.

Thin-Ereignisse

Thin-Ereignisse sind einfache Ereignisse, auf die Sie über den API v2-Namespace zugreifen können. Thin-Ereignisse haben ein detaillierteres Berechtigungsmodell und ihre Nutzlasten enthalten keine API-Versionsdaten, sondern nur die IDs der Objekte, die sich auf das Ereignis beziehen. Dies hilft bei der Aktualisierung von Integrationen, die Ereignisse empfangen und mit einem gut typisierten Stripe SDK erstellt wurden. Thin Events:

Fügen Sie die Eigenschaft data hinzu, die zusätzliche Informationen zu dem Ereignis enthalten kann.
Sind vollständig in die SDKs for API v2 eingegeben.

Sie können Ereignis-Objekte für jede Benachrichtigung vom Endpoint /v2/core/events abrufen. Diese API-Objekte enthalten die Eigenschaft data, die zusätzliche Details zum Thin-Ereignis bereitstellen kann.

Anwendungsfehler vermeiden

Wenn Ihre Anwendung ein entsprechendes API-Objekt in Verbindung mit einem Ereignis benötigt (zum Beispiel dem Zähler), müssen Sie die Stripe API aufrufen, um den neuesten Status des Objekts zu erhalten. Obwohl diese Methode einen zusätzlichen Netzwerkaufruf an Stripe erfordert, hilft sie, Anwendungsfehler zu vermeiden, die durch veraltete Objektdaten verursacht werden (z. B. Race-Bedingungen). Die SDKs for API v2 enthalten Helper-Methoden, mit denen Sie Datensätze abrufen können, die einem Ereignis zugeordnet sind.

Beispiel für eine Thin-Ereignisnutzlast

Nachfolgend finden Sie ein Beispiel für das Ereignis v1.billing.meter.error_report_triggered. Das Feld related_object enthält die id des Objekts, jedoch nicht den Objektdatensatz.

{
  "id": "evt_test_65R9Ijk8dKEYZcXeRWn16R9A7j1FSQ3w3TGDPLLGSM4CW0",
  "object": "v2.core.event",
  "type": "v1.billing.meter.error_report_triggered",
  "livemode": false,
  "created": "2024-09-17T06:20:52.246Z",
  "related_object": {
    "id": "mtr_test_61R9IeP0SgKbYROOx41PEAQhH0qO23oW",
    "type": "billing.meter",
    "url": "/v1/billing/meters/mtr_test_61R9IeP0SgKbYROOx41PEAQhH0qO23oW"
  }
}

Beispiel für die Nutzlast eines Snapshot-Ereignisses

Sehen Sie sich das folgende Beispiel eines setup_intent.created-Snapshot-Ereignisses an, das die Objektdefinition enthält, wie sie zum Zeitpunkt des Auslösens des Ereignisses war:

{
  "id": "evt_1NG8Du2eZvKYlo2CUI79vXWy",
  "object": "event",
  "api_version": "2019-02-19",
  "created": 1686089970,

Rufen Sie zusätzliche Informationen ab, die mit einem Thin-Ereignis verknüpft sind

Es gibt zwei Arten von Informationen, die Sie zu einem Thin-Ereignis abrufen können:

Definition der zugehörigen Objektressource: Jedes Thin-Ereignis beschreibt ein bestimmtes Ereignis im Zusammenhang mit einem Stripe-Objekt. Verwenden Sie die Methode fetchRelatedObject(), um die neueste Version des mit dem Ereignis verknüpften Objekts abzurufen. Wenn Sie beispielsweise ein v1.billing.meter.error_report_triggered-Ereignis erhalten, ruft fetchRelatedObject() die aktuelle Version des Zählerobjekts ab, das einen Fehlerbericht ausgelöst hat.
Zusätzliche Ereignis-Nutzdatenfelder: Thin-Ereignisse können zusätzliche Kontextdaten enthalten, die nur mit der API abgerufen werden können. Verwenden Sie den Aufruf retrieve() mit der Thin-Ereignis-ID, um diese zusätzlichen Nutzlast-Felder abzurufen. Wenn Sie beispielsweise ein v1.billing.meter.error_report_triggered-Ereignis mit der API abrufen, wird ein zusätzlicher data-Hash zurückgegeben. Dieser Hash enthält Kontextfelder zu den ausgelösten Fehlern, zum Beispiel den Zeitpunkt des Auftretens des Validierungsfehlers, eine Liste von Beispielfehlermeldungen und die Anzahl der Validierungsfehler.

Das folgende Beispiel zeigt, wie die zugehörige Objektdefinition und zusätzliche Ereignis-Nutzlast-Felder abgerufen werden, die einem Thin-Ereignis zugeordnet sind:

Berechtigungen für Ereignisse

Weisen Sie Ihrem Nutzerkonto eine Admin- oder Entwicklerrolle zu, um ein Ereignis im Dashboard anzuzeigen. Um ein Ereignis mit der API abzurufen, verwenden Sie entweder einen API-Geheimschlüssel, mit dem Sie standardmäßig alle Ereignistypen anzeigen können, oder einen eingeschränkten API-Schlüssel mit aktiviertem Read-Zugriff für die Ressource des jeweiligen Ereignistyps. Gewähren Sie zum Beispiel Read-Zugriff auf payment_intent-Ressourcen in Ihrem eingeschränkten API-Schlüssel, um die payment_intent.succeeded events programmgesteuert abzurufen.

Zugriff auf Ereignisse

Auf der Registerkarte Ereignisse in Workbench können Sie auf Ereignisse der letzten 13 Monate zugreifen:

Bei Ereignissen, die weniger als 15 Tage alt sind, können Sie die vollständige Nutzlast des Ereignisses anzeigen, die Zustellversuche sehen und diese Ereignisse manuell erneut senden.
Bei Ereignissen, die 16 bis 30 Tage alt sind, können Sie auf die gesamte Ereignisnutzlast zugreifen, aber Sie können sie nicht erneut senden oder Zustellversuche anzeigen.
Für Ereignisse, die älter als 30 Tage sind, können Sie nur eine Übersichtsansicht sehen, die abgeschnittene Felder der ursprünglichen Ereignisdaten enthält. Erneutes Senden und Anzeigen von Zustellversuchen sind für diese Ereignisse nicht verfügbar.

Verwenden Sie die Retrieve Event API und die List Events API, um auf Ereignisse mit ihrer vollständigen Nutzlast der letzten 30 Tage zuzugreifen.

Grenzwerte für Ereignisziele

Sie können maximal 16 Ereignisziele in jedem Live-Modus- oder Sandbox-Konto registrieren. Wenn Sie ein Snapshot-Ereignisziel mit einer anderen Version als der Standardversion Ihres Händlers/Ihrer Händlerin registrieren, können Sie bis zu drei einmalig versionierte Snapshot-Ereignisziele registrieren.

Ein Ereignisziel verwalten

Um ein Ereignisziel im Dashboard zu erstellen, zu löschen und zu aktualisieren, öffnen Sie die Registerkarte Webhooks in Workbench oder verwenden Sie die Event Destinations API.

Ein Ereignisziel deaktivieren

Sie können ein Ereignisziel deaktivieren. Nach dem Deaktivieren sendet Stripe keine Ereignisse mehr an dieses Ziel. Nachdem Sie ein Ziel wieder aktiviert haben, sendet Stripe weiterhin Ereignisse an das Ziel.