Ereignisziele

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

Notiz

Wenn die Registerkarte Ereignisziele in Workbench oder im Entwickler-Dashboard nicht angezeigt wird, aktivieren Sie Ereignisziele in Ihrer Einstellung für die Produktvorschau.

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.

Anwendungsszenarien

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 benachrichtigen, wenn eine Kundin/ein Kunde eine Zahlung bestätigt
Interne Anspruchsprüfung einleiten, wenn eine Kundin/ein Kunde eine Zahlung angefochten hat
Nutzer/in Zugriff gewähren, wenn sie/er erfolgreich wiederkehrende Abonnementzahlungen leistet

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.

Eigenschaften	Snapshot-Ereignisse	Thin-Ereignisse
Erstellt von	API v1 Änderungen am Ressourcen-Status	API v2 Änderungen am Ressourcen-Status
Nutzlast	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
SDK-Typisierung	Ohne Typ	Typisiert
Versionierung	Versioniert nach API-Version	Nicht versioniert, sodass Sie Ihre Integration aktualisieren können, ohne Ihren Webhook-Endpoint konfigurieren 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 events are lightweight events you can access through the API v2 namespace. Thin events have a more granular permissions model and their payloads contain no API-versioned data, only the IDs of the objects related to the event. This helps update integrations that receive events and are built with a well-typed Stripe SDK. 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"
  }
}

Daher ist die Nutzlast eines Thin-Ereignisses viel kleiner als die Nutzlast eines Snapshot-Ereignisses. Nachfolgend finden Sie ein Beispiel für ein Snapshot-Ereignis vom Typ invoice.created:

{
  "object": {
    "id": "in_1KnN0G589O8KAxCGfVSpD0Pj",
    "object": "invoice",
    "account_country": "US",

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

Über die Registerkarte Ereignisse in Workbench können Sie auf Ereignisse zugreifen, die in den letzten 13 Monaten erstellt wurden. Im Abschnitt Ereignisübermittlungen können Sie jedoch nur Übermittlungsversuche manuell erneut senden oder anzeigen, die höchstens 15 Tage alt sind. Für Ereignisse, die älter als 30 Tage sind, können Sie auf eine Übersichtsansicht zugreifen, die nur gekürzte Felder der ursprünglichen Ereignisdaten enthält.

Sie können auf schlanke Ereignisse innerhalb der letzten 30 Tage zugreifen, indem Sie das Ereignis Ereignis abrufen und Ereignis auflisten API v2 endpoints verwenden. Um auf Snapshot-Ereignisse innerhalb der letzten 30 Tage zuzugreifen, verwenden Sie die Ereignisse Ereignis abrufen und Ereignis auflisten API v1 endpoints.

Ein Ereignisziel verwalten

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

Ein Ereignisziel deaktivieren

Sie können Ereignisziele deaktivieren. Nachdem Sie ein Ziel deaktiviert haben, sendet Stripe keine Ereignisse mehr an dieses Ziel. Wenn Sie das Ziel wieder aktivieren, sendet auch Stripe wieder Ereignisse an dieses.