# Integration mit Ereignissen Senden Sie Ereignisse von Stripe an Webhook-Endpoints und Cloud-Dienste. > [Thin-Ereignisse](https://docs.stripe.com/event-destinations.md#thin-events) für API v1-Ressourcen sind in einer privaten Vorschau verfügbar. Sie können sie verwenden, um Integrations-Upgrades ohne Änderungen an Ihrer Webhook-Konfiguration zu optimieren. Bislang haben Thin-Ereignisse nur API v2-Ressourcen unterstützt. [Erfahren Sie mehr und beantragen Sie Zugang](https://docs.google.com/forms/d/e/1FAIpQLSeEkqzB02afvlklMkqwA6wsBH90eW8gxmc-hBOvqe2N6TRujQ/viewform?usp=dialog). Richten Sie ein Ereignisziel ein, um Ereignisse von Stripe über verschiedene Zieltypen hinweg zu empfangen, darunter Webhook-Endpoints, [Amazon EventBridge](https://docs.stripe.com/event-destinations/eventbridge.md) und [Azure Event Grid](https://docs.stripe.com/event-destinations/eventgrid.md). Sie können Ereignisse auf folgende Weise empfangen: - Abgeschlossene [Momentaufnahme-Ereignisse](https://docs.stripe.com/event-destinations.md#choosing-event-format) für eine Point-in-Time-Ansicht Ihrer Ressourcen - Leichte, [dünne Ereignisse](https://docs.stripe.com/event-destinations.md#thin-events), 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 Senden Sie Ereignisse über [Amazon EventBridge](https://docs.stripe.com/event-destinations/eventbridge.md) an ein AWS-Konto, über [Azure Event Grid](https://docs.stripe.com/event-destinations/eventgrid.md) an ein Azure-Abonnement oder über [Webhook-Endpoints](https://docs.stripe.com/webhooks.md) an einen HTTPS-Endpoint. ## Ereignis-Übersicht Wenn ein Ereignis eintritt, generiert Stripe ein neues`Event`-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 `Event`-Objekten: - [Thin-Ereignisse](https://docs.stripe.com/api/v2/events.md): Wenn es an Ihr Ereignisziel übermittelt wird, kommt ein Thin-Ereignis 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ändige `Ereignis`-Objekt oder den letzten Zustand der zugehörigen Ressourcen anzufordern. Diese werden von API v2 endpoints generiert. Hier finden Sie eine [vollständige Liste der Thin-Ereignisse](https://docs.stripe.com/api/v2/core/events/event-types.md). - [Momentaufnahme-Ereignisse](https://docs.stripe.com/api/events.md): Wenn es an Ihr Ziel geliefert wird, erhalten Sie ein Momentaufnahme-Ereignis als vollständiges `Event`-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 eine`previous_attributes`-Eigenschaft, die die Änderung anzeigt, falls zutreffend. Siehe eine [vollständige Liste der Momentaufnahme-Ereignisse](https://docs.stripe.com/api/events/types.md). ### 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. | Charaktereigenschaften | Snapshot-Ereignisse | Thin-Ereignisse | | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | Erstellt von | API v1 Änderungen am Ressourcen-Status | API v2 Änderungen des Ressourcenstatus | | Gelieferte Nutzlast | **Groß**: Enthält einen Snapshot des API-Objekts, das sich auf das Ereignis bezieht | **Klein**: Enthält eine ID des API-Objekts, das sich auf das Ereignis bezieht, in einer einfachen („leichten“) Ereignisbenachrichtigung | | Zugreifen auf zusätzliche Daten zum Verarbeiten des Ereignisses. | 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 aus der API ab, oder rufen Sie das vollständige [Ereignis](https://docs.stripe.com/api/v2/events.md) von`v2/events` ab. Die vollständige Ereignisnutzlast kann zusätzliche Details zum 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 | | API zum Anzeigen von Ereignissen | [Events v1 API](https://docs.stripe.com/api/events.md) | [Events v2 API](https://docs.stripe.com/api/v2/events.md) | ### Beispiel für eine Nutzlast für eine Benachrichtigung zu dünnen Ereignissen Im Folgenden finden Sie ein Beispiel für ein Thin-Ereignis vom Typ `v2.core.account.updated`Das Feld `related_object` enthält die `ID` des Objekts, das Feld `reason` gibt an, was das Ereignis ausgelöst hat, und das Feld `changes` zeigt, was sich an dem Objekt geändert hat. ```json { "id": "evt_test_65UIRNU7G1XbhCfOim416TgmEI4ASQ3jHxXt8RFwXoeVwO", "object": "v2.core.event", "type": "v2.core.account.updated", "livemode": false, "created": "2026-03-09T13:00:28.435Z", "context": null, "reason": { "type": "request", "request": { "id": "req_v2y9y15XqG3Futmjg", "idempotency_key": "ik_TgmEI3jHxXt8RFw4jS7ve2QcAReDQWBjPAkAEUm" } }, "related_object": { "id": "acct_1T93Q4Pmpb34Vto6", "type": "v2.core.account", "url": "/v2/core/accounts/acct_1T93Q4Pmpb34Vto6" }, "data": {}, "changes": { "before": { "display_name": "Example Account" }, "after": { "display_name": "Updated Example Account" } } } ``` ### 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: ```json { "id": "evt_1NG8Du2eZvKYlo2CUI79vXWy", "object": "event", "api_version": "2019-02-19", "created": 1686089970, "data": { "object": { "id": "seti_1NG8Du2eZvKYlo2C9XMqbR0x", "object": "setup_intent", "application": null, "automatic_payment_methods": null, "cancellation_reason": null, "client_secret": "seti_1NG8Du2eZvKYlo2C9XMqbR0x_secret_O2CdhLwGFh2Aej7bCY7qp8jlIuyR8DJ", "created": 1686089970, "customer": null, "description": null, "flow_directions": null, "last_setup_error": null, "latest_attempt": null, "livemode": false, "mandate": null, "metadata": {}, "next_action": null, "on_behalf_of": null, "payment_method": "pm_1NG8Du2eZvKYlo2CYzzldNr7", "payment_method_options": { "acss_debit": { "currency": "cad", "mandate_options": { "interval_description": "First day of every month", "payment_schedule": "interval", "transaction_type": "personal" }, "verification_method": "automatic" } }, "payment_method_types": [ "acss_debit" ], "single_use_mandate": null, "status": "requires_confirmation", "usage": "off_session" } }, "livemode": false, "pending_webhooks": 0, "request": { "id": null, "idempotency_key": null }, "type": "setup_intent.created" } ``` ## 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ändigen `Event`-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 `data`-Hash. Zum Beispiel enthält ein`v1.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 `changes`-Hash. In der folgenden Tabelle sind die zusätzlichen Daten aufgeführt, die im vollständigen [Ereignis](https://docs.stripe.com/api/v2/events.md)-Objekt im Vergleich zur ursprünglichen Benachrichtigung zur Verfügung stehen: | Eigenschaftsname | Ereignisbenachrichtigung | Ereignis | | ---------------------------- | ------------------------ | -------- | | Ereignistyp | ✅ | ✅ | | ID der zugehörigen Ressource | ✅ | ✅ | | Ereignis-ID | ✅ | ✅ | | Zeitstempel erstellt | ✅ | ✅ | | Ursache | ✅ | ✅ | | Änderungen | ❌ | ✅ | | Daten | ❌ | ✅ | 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 event` erhalten, ruft `fetchRelatedObject()` das Zählerobjekt ab, das einen Fehlerbericht ausgelöst hat. 1. **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: #### Java ```java 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 mit`fetchEvent()` abrufen, wird das resultierende Objekt als `{EventType}Event` typisiert. ## Berechtigungen für Ereignisse Weisen Sie Ihrem Nutzerkonto eine [Admin- oder Entwicklerrolle](https://docs.stripe.com/get-started/account/teams/roles.md) zu, um ein Ereignis im Dashboard anzuzeigen. Um ein Ereignis mit der API abzurufen, verwenden Sie entweder einen [API-Geheimschlüssel](https://docs.stripe.com/keys.md#create-api-secret-key), mit dem Sie standardmäßig alle Ereignistypen anzeigen können, oder einen [eingeschränkten API-Schlüssel](https://docs.stripe.com/keys.md#create-restricted-api-secret-key) 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](https://docs.stripe.com/api/v2/core/events/retrieve.md) und [List Events](https://docs.stripe.com/api/v2/core/events/list.md) API, um auf Ereignisse mit ihrer vollen Nutzlast aus den letzten 30 Tagen 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](https://dashboard.stripe.com/webhooks) in Workbench oder verwenden Sie die [Event Destinations API](https://docs.stripe.com/api/v2/event-destinations/.md). ## 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.