# 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 stellen zwei Versionen von `Event`-Objekten bereit: - [Thin-Ereignisse (v2)](https://docs.stripe.com/api/v2/events.md): Ein Thin-Ereignis sendet eine einfache Benachrichtigung, die nur begrenzte Informationen über das v2-`Event`-Objekt und das betroffene Objekt enthält. Sie können einen nachfolgenden API-Aufruf durchführen, um das vollständige `Event`-Objekt oder die zugehörige Ressource abzurufen. Thin-Ereignisse 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). - [Snapshot-Ereignisse](https://docs.stripe.com/api/events.md): Ein Snapshot-Ereignis sendet eine Benachrichtigung, die das vollständige `Event`-Objekt enthält, einschließlich eines letztendlich konsistenten Snapshots der aktualisierten Ressource. Da diese Daten zum Zeitpunkt der Verarbeitung veraltet sein können, sollten Sie die neueste Version der Ressource über die API abrufen. Im Gegensatz zu Benachrichtigungen über Thin-Ereignisse sind die zugestellten Snapshot-Ereignisse versioniert. Deshalb müssen Sie die Versionen sowohl auf Ihrem Ereignisziel als auch auf Ihrem Client verwalten. Diese Ereignisse werden sowohl von API v1 endpoints als auch von API v2 endpoints generiert. Sie enthalten eine `previous_attributes`-Eigenschaft, die gegebenenfalls die Änderung angibt. Hier finden Sie eine [vollständige Liste der Snapshot-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 | Der Ressourcenstatus ändert sich sowohl für API v1 als auch für API v2 | 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) | Wenn Sie [Accounts v2](https://docs.stripe.com/connect/accounts-v2/migrate-integration.md) verwenden, können Sie sowohl Snapshot- als auch Thin-Ereignisse überwachen. ### Beispiel für eine Nutzlast für eine Benachrichtigung zu dünnen Ereignissen Das folgende Beispiel zeigt eine Thin-Event-Benachrichtigung vom Typ `v2.core.account.updated`. Die Eigenschaft `id` in der Benachrichtigungs-Nutzlast enthält die ID des zugehörigen `Event`-Objekts. Der Hash `reason` enthält Informationen darüber, was das Ereignis ausgelöst hat, und der Hash `related_object` enthält Informationen über das zugehörige Objekt, einschließlich seiner ID. Um auf weitere Ereigniseigenschaften wie `data` und `changes` zuzugreifen, verwenden Sie die Methode `fetchEvent()`, um das vollständige `Event`-Objekt abzurufen. Sie können das zugehörige Objekt auch mit der Methode `fetchRelatedObject()` abrufen. ```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" } } ``` ### 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 | ✓ Unterstützt | ✓ Unterstützt | | ID der zugehörigen Ressource | ✓ Unterstützt | ✓ Unterstützt | | Ereignis-ID | ✓ Unterstützt | ✓ Unterstützt | | Zeitstempel erstellt | ✓ Unterstützt | ✓ Unterstützt | | Ursache | ✓ Unterstützt | ✓ Unterstützt | | Änderungen | ❌ Nicht unterstützt | ✓ Unterstützt | | Daten | ❌ Nicht unterstützt | ✓ Unterstützt | 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 Um ein Ereignis im Dashboard anzuzeigen, weisen Sie Ihrem Nutzerkonto die [Rolle Admin oder Entwickler/in](https://docs.stripe.com/get-started/account/teams/roles.md) zu. Um ein Ereignis über die API abzurufen, verwenden Sie entweder einen [geheimen API-Schlüssel](https://docs.stripe.com/keys.md#create-api-secret-key), der es Ihnen standardmäßig ermöglicht, alle Ereignistypen anzuzeigen, oder einen [eingeschränkten API-Schlüssel](https://docs.stripe.com/keys.md#create-restricted-api-key), bei dem der Zugriff `Lesen` für die Ressource des spezifischen Ereignistyps aktiviert ist. Beispielsweise können Sie für Ihren eingeschränkten API-Schlüssel den Zugriff `Lesen` auf `payment_intent`-Ressourcen gewähren, um `payment_intent.succeeded-Ereignisse` 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.