Ereignisziele

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
Access additional data to process event.	Fetch the latest object definition from the API. The object definition in the event payload might be outdated by the time you process the event.	Fetch the latest object from the API or retrieve the full event from `v2/events`. The full event payload may include extra details about the event. For example, the payload for a `v1.billing.meter.error_report_triggered` event includes information about the types and frequency of errors raised.
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"
  }
}

Example snapshot event payload

View the following example of an setup_intent.created snapshot event, which includes the object definition as it was when the event was raised:

{
  "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

In the Events tab in Workbench, you can access events within the last 13 months:

For events less than 15 days old, you can view the full event payload, see the delivery attempts, and manually resend these events.
For events 16-30 days old, you can access the full event payload, but you can’t resend them or view delivery attempts.
For events older than 30 days, you can only see a summary view, which includes truncated fields of the original event data. Resending and viewing delivery attempts aren’t available for these events.

Use the Retrieve event and List events APIs to access events with their full payload from the past 30 days.

Event destination limits

You can register a maximum of 16 event destinations in each livemode or sandbox account. When registering a snapshot event destination with a version different from your merchant’s default version, you can register up to three uniquely versioned snapshot event destinations.

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.