Integration mit Ereignissen

Einrichten eines Ereignisziels für den Empfang von Ereignissen von Stripe über mehrere Zieltypen, einschließlich Webhook-Endpoints undAmazon EventBridge. Sie können Ereignisse erhalten in:

• Abgeschlossene Momentaufnahme-Ereignisse für eine Point-in-Time-Ansicht Ihrer Ressourcen
• Leichte, dünne Ereignisse, um sicherzustellen, dass Sie immer auf die aktuellsten Daten zurückgreifen, die Ihnen helfen, den Upgrade-Prozess Ihrer Integration zu vereinfachen

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

Wenn ein Ereignis eintritt, generiert Stripe ein neuesEreignis-Objekt. Eine einzelne API-Anfrage kann zur Erstellung mehrerer Ereignisse führen. Das Erstellen eines neuen Abonnements für einen Kunden/Kundin kann z. B. die Ereignisse customer.subscription.created und payment_intent.succeeded auslösen. Für programmgesteuerte Integrationen empfehlen wir, dass Sie ein Ereignisziel konfigurieren, um diese Ereignisse zu empfangen, sobald sie auftreten. Die Art und Weise, wie das Ereignis strukturiert und an Ihren Zielort geliefert wird, hängt von dem Format ab, das Sie für den Empfang wählen.

Wir bieten zwei verschiedene Formate von Ereignis-Objekten:

• Dünne Ereignisse: Wenn es an Ihr Ereignisziel übermittelt wird, kommt ein dünnes Ereignis (ein „Thin Event“) als einfache Ereignisbenachrichtigung an, die nur die ID der betroffenen Objekte enthält. Sie können einen nachfolgenden API-Aufruf ausführen, um das vollständigeEreignis-Objekt oder den letzten Zustand der zugehörigen Ressourcen anzufordern. Diese werden von API v2 endpoints generiert. Siehe eine vollständige Liste der Thin-Ereignisse.
• Momentaufnahme-Ereignisse: Wenn es an Ihr Ziel geliefert wird, erhalten Sie ein Momentaufnahme-Ereignis als vollständiges Ereignis-Objekt mit einer letztendlich konsistenten Momentaufnahme der Ressource, die sich geändert hat. Da diese Daten zum Zeitpunkt Ihrer Verarbeitung veraltet sein können, empfehlen wir, die neueste Version der Ressource von der API abzurufen. Im Gegensatz zu Benachrichtigungen zu dünnen Ereignissen sind die übermittelten Momentaufnahme-Ereignisse versioniert, was bedeutet, dass Sie die Versionen sowohl auf Ihrem Stripe-Ereignisziel als auch auf Ihrem Client verwalten müssen. Diese Ereignisse werden nur von API v1 endpoints generiert. Sie umfassen eineprevious_attributes-Eigenschaft, die die Änderung anzeigt, falls zutreffend. Siehe eine vollständige Liste der Momentaufnahme-Ereignisse.

Format wählen

Verwenden Sie dünne Ereignisse in folgenden Fällen:

• Datenintegrität ist von entscheidender Bedeutung, und Ihre Anwendung muss auf den aktuellsten Informationen basieren.
• Sie möchten die Versionsverwaltung vereinfachen, indem Sie Upgrades nur auf der Client-Seite verwalten.
• Sie erstellen eine moderne, typsichere Anwendung und möchten die Vorteile der SDK-Typisierung nutzen.

Verwenden Sie Momentaufnahme-Ereignisse in folgenden Fällen:

• Sie müssen die spezifischen Felder überwachen, die sich geändert haben, ohne einen nachfolgenden API-Aufruf durchzuführen.
• Ihre Integration erfordert eine Point-in-Time-Ansicht der Ressourcendefinition und kann die Arbeit mit letztendlich konsistenten Daten tolerieren.

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

Beispiel für eine Nutzlast für eine Benachrichtigung zu dünnen Ereignissen

Im Folgenden finden Sie ein Beispiel für ein v1.billing.meter.error_report_triggered-Ereignis. Der Daten-Hash unten ist in der Ereignisbenachrichtigung, die an das Ziel gesendet wird, nicht verfügbar. Das Feld related_object enthält die ID des Objekts, schließt aber nicht den Objektdatensatz selbst ein.

{
  "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"
  }
  "data": {
    "developer_message_summary": "There is 1 invalid event",
    "reason": {
      "error_count": 1,
      "error_types": [
        {
          "code": "meter_event_no_customer_defined",
          "error_count": 1,
          "sample_errors": [
            {
              "error_message": "Customer mapping key stripe_customer_id not found in payload.",
              "request": {
                "id": "",
                "idempotency_key": "37c741d8-1f7e-4adc-af16-afdca1d73b37"
              }
            }
          ]
        }
      ]
    },
    "validation_end": "2024-08-28T20:54:10.000Z",
    "validation_start": "2024-08-28T20:54:00.000Z"
  }
}

Beispiel für eine Nutzlast eines Momentaufnahmen-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,

Verwenden von Thin-Events

Integrieren Sie dünne Ereignisse, indem Sie die an Ihr Ziel gesendete Ereignisbenachrichtigung verwenden, um weitere Details von der API abzurufen.

Verarbeiten der Ereignisbenachrichtigung

Die erste Benachrichtigung enthält nur minimale Daten. Wählen Sie bei der Verarbeitung der Ereignisbenachrichtigung einen von drei Ansätzen, je nachdem, welche Informationen Ihre Integration benötigt:

1. Abrufen des vollständigen Ereignisses: Verwenden Sie die fetchEvent()-Methode zum Abrufen des vollständigenEreignis-Objekts, wenn Sie mehr Informationen benötigen, als der neueste Zustand des zugehörigen Objekts liefert. Das vollständige Ereignisobjekt kann zwei Arten von zusätzlichen Daten enthalten:
   • Kontextinformationen über das Ereignis selbst, verfügbar im Daten-Hash. Zum Beispiel enthält einv1.billing.meter.error_report_triggered-Ereignis Details zu den Typen und eine Zusammenfassung der Validierungsfehler in diesem Feld.
   • Die vorherigen Werte aller Attribute, die sich bei der Ressource geändert haben, verfügbar im Hash der Änderungen.

In der folgenden Tabelle sind die zusätzlichen Daten aufgeführt, die im vollständigen Ereignis-Objekt im Vergleich zur ursprünglichen Benachrichtigung zur Verfügung stehen:

1. Abrufen des aktuellen Status des zugehörigen Objekts: Verwenden Sie die Methode fetchRelatedObject(), um die neueste Version des Objekts abzurufen, das mit dem Ereignis verknüpft ist. Wenn Sie z. B. ein v1.billing.meter.error_report_triggered-Ereignis erhalten, ruft fetchRelatedObject() das Zählerobjekt ab, das einen Fehlerbericht ausgelöst hat.
2. Benachrichtigung sofort verarbeiten: Wenn der Ereignistyp und die Ressourcen-ID in der Benachrichtigung für Ihren Use Case ausreichend sind, können Sie die Benachrichtigung ohne zusätzlichen API-Aufruf verarbeiten.

Das folgende Beispiel zeigt, wie die zugehörige Objektdefinition und zusätzliche Ereignisnutzlastfelder abgerufen werden, die beim Verarbeiten einer Thin-Ereignisbenachrichtigung verknüpft sind:

com.stripe.model.EventNotification eventNotification = client.parseEventNotification(payload, signatureHeader, endpointSecret);
com.stripe.model.v2.Event event = client.v2().core().events().retrieve(eventNotification.getId());
if (event instanceof V1BillingMeterErrorReportTriggeredEvent) {
  V1BillingMeterErrorReportTriggeredEvent postedEvent = (V1BillingMeterErrorReportTriggeredEvent) event;
  // On each type of event, the Stripe library provides a "fetchRelatedObject" method
  // that performs a network request to Stripe to fetch the latest version
  // of the object directly associated with the event, in this case, an
  // "Meter" object.
  Meter op = postedEvent.fetchRelatedObject();
}

SDK-Typisierung

Dünne Ereignisse und ihre Benachrichtigungen werden vollständig in den SDKs eingegeben.

• Ereignisbenachrichtigung: Die anfängliche, leichte Nutzlast, die an Ihr Ereignisziel übermittelt wird, wird als {EventType}EventNotification typisiert.
• Ereignis: Nachdem Sie das vollständige Ereignis von der API mitfetchEvent() abrufen, wird das resultierende Objekt als{EventType}Ereignis typisiert.

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. Nachdem Sie die Option deaktiviert haben, sendet Stripe keine Ereignisse mehr an dieses Ziel. Nachdem Sie ein Ziel wieder aktiviert haben, setzt Stripe das Senden von Ereignissen an das Ziel fort.