# Ereignisse einrichten

Stripe-Ereignisse in Ihrer Anwendung empfangen, verifizieren und verarbeiten.

Dieser Leitfaden beschreibt, wie Sie einen Ereignis-Handler erstellen, der Ereignisse empfängt, jede Anfrage verifiziert und Ereignisse in Ihrer Anwendung verarbeitet.

[Code-Schnellstart](https://docs.stripe.com/webhooks/quickstart.md)

Wenn Sie noch nicht damit vertraut sind, wie Stripe-Ereignisse strukturiert sind oder welches Format Sie verwenden sollen, lesen Sie zuerst [Funktionsweise von Ereignissen](https://docs.stripe.com/events/how-events-work.md).

## Wählen Sie Ihr Ereignisformat aus

Verwenden Sie Thin-Ereignisse („Thin Events“) für neue Integrationen. Thin-Ereignisse sind unversioniert, in den Stripe-SDKs typisiert und geben den neuesten Ressourcenstatus zurück, wenn Sie diese abrufen – Sie müssen also keine API-Versionsanpassung an Ihrem Ereignisziel verwalten. Thin-Ereignisse werden von API v1- und API v2-Ressourcen generiert. Die vollständige Liste der unterstützten Typen finden Sie im [Katalog der Thin-Ereignisse](https://docs.stripe.com/api/v2/core/events/event-types.md).

Verwenden Sie Snapshot-Ereignisse nur, wenn einer der folgenden Punkte zutrifft:

- Ein Drittanbieter-Tool oder eine Integration erfordert den Empfang des vollständigen Payloads des `Event`-Objekts.
- Sie benötigen die vorherigen Werte geänderter Attribute einer Ressource, ohne einen zusätzlichen API-Aufruf durchzuführen.

Snapshot-Ereignisse senden das vollständige `Event`-Objekt, einschließlich eines Point-in-Time-Snapshots der zugehörigen Ressource. Sie enthalten eine Eigenschaft `previous_attributes`, die anzeigt, welche Felder geändert wurden. Sie werden nach API-Version versioniert, was erfordert, dass Sie Ihre Endpoint-API-Version an Ihre SDK-Version anpassen.

Einen detaillierten Vergleich finden Sie unter [Funktionsweise von Ereignissen](https://docs.stripe.com/events/how-events-work.md#choosing-event-format).

## Ereignis-Handler erstellen

Fügen Sie Ihrem Server einen Endpoint hinzu, der `POST`-Anfragen von Stripe akzeptiert. Das primäre Beispiel verwendet Thin-Ereignisse („Thin Events“), die wir für neue Integrationen empfehlen. Der Code unterscheidet sich je nachdem, welches Ereignisformat Sie verwenden.

#### Thin-Ereignisse

Verwenden Sie `parseEventNotification()`, um die Signatur zu validieren und eine typisierte Ereignis-Benachrichtigung zurückzugeben. Rufen Sie `fetchRelatedObject()` auf, um den neuesten Ressourcenstatus abzurufen, oder `fetchEvent()`, wenn Sie zusätzliche Ereignisdaten wie geänderte Felder benötigen.

#### Node.js

```javascript

// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
// Find your keys at https://dashboard.stripe.com/apikeys.
const stripe = require('stripe')('<<YOUR_SECRET_KEY>>');

// This example uses Express to receive webhooks
const express = require('express');
const app = express();
const endpointSecret = 'whsec_...';

app.post('/webhook', express.raw({type: 'application/json'}), async (request, response) => {
  const sig = request.headers['stripe-signature'];
  let eventNotification;

  try {
    eventNotification = client.parseEventNotification(request.body, sig, endpointSecret);
  } catch (err) {
    response.status(400).send(`Webhook Error: ${err.message}`);
    return;
  }

  // Handle the event notification
  switch (eventNotification.type) {
    case 'v1.billing.meter.error_report_triggered':
      // fetchRelatedObject() retrieves the latest version of the related resource
      const meter = await eventNotification.fetchRelatedObject();
      console.log('Meter error for:', meter.display_name);
      break;
    default:
      console.log(`Unhandled event type: ${eventNotification.type}`);
  }

  response.json({received: true});
});

app.listen(4242, () => console.log('Running on port 4242'));
```

#### Snapshot-Ereignisse (Ausnahmefälle)

Verwenden Sie `constructEvent()`, um die Webhook-Signatur zu verifizieren, und überprüfen Sie dann das Feld `type`, um zu bestimmen, welches Ereignis aufgetreten ist. Das `data.object` jedes Ereignisses enthält einen Snapshot der betroffenen Ressource in dem Zustand, in dem sie sich befand, als das Ereignis generiert wurde. Da dieser Snapshot veraltet sein kann, sollten Sie die neueste Ressource über die API abrufen, bevor Sie eine wichtige Aktion ausführen.

#### Node.js

```javascript

// Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
// Find your keys at https://dashboard.stripe.com/apikeys.
const stripe = require('stripe')('<<YOUR_SECRET_KEY>>');

// This example uses Express to receive webhooks
const express = require('express');
const app = express();
const endpointSecret = 'whsec_...';

app.post('/webhook', express.raw({type: 'application/json'}), (request, response) => {
  const sig = request.headers['stripe-signature'];
  let event;

  try {
    event = stripe.webhooks.constructEvent(request.body, sig, endpointSecret);
  } catch (err) {
    response.status(400).send(`Webhook Error: ${err.message}`);
    return;
  }

  // Handle the event
  switch (event.type) {
    case 'payment_intent.succeeded':
      const paymentIntent = event.data.object;
      console.log('PaymentIntent was successful!');
      break;
    case 'payment_method.attached':
      const paymentMethod = event.data.object;
      console.log('PaymentMethod was attached to a Customer!');
      break;
    // ... handle other event types
    default:
      console.log(`Unhandled event type ${event.type}`);
  }

  // Return a 200 response to acknowledge receipt of the event
  response.json({received: true});
});

app.listen(4242, () => console.log('Running on port 4242'));
```

Starten Sie nach Hinzufügen des neuen Endpoints Ihren Server.

## Installieren und richten Sie die Stripe-CLI ein

Installieren Sie die Stripe-CLI mit [npm](https://www.npmjs.com/):

```bash
npm install -g @stripe/cli@latest
```

Melden Sie sich nach der Installation bei Ihrem Stripe-Konto an:

```bash
stripe login
```

Nachdem Sie die CLI installiert haben, können Sie auch [Agent-Tools](https://docs.stripe.com/cli/agent/setup) installieren oder die [Autovervollständigung](https://docs.stripe.com/cli/completion) einrichten.

> Weitere Installationsoptionen für Windows, macOS, Linux und Docker finden Sie in der [Stripe-CLI-Readme](https://github.com/stripe/stripe-cli#installation) auf GitHub.

Nachdem Sie die Stripe-CLI installiert haben, führen Sie `stripe login` in der Befehlszeile aus, um einen Kopplungscode zu generieren und mit Ihrem Stripe-Konto zu verknüpfen. Drücken Sie die **Eingabetaste**, um Ihren Browser zu starten und sich anzumelden.

```bash
stripe login
Your pairing code is: humour-nifty-finer-magic
Press Enter to open up the browser (^C to quit)
```

Der generierte API-Schlüssel ist 90 Tage lang gültig. Sie können ihn unter [API-Schlüssel](https://dashboard.stripe.com/apikeys) im Dashboard ändern oder löschen.

> Sie können eine projektspezifische Konfiguration erstellen, indem Sie das Flag [–project-name](https://docs.stripe.com/cli/login#login-project-name) einfügen, wenn Sie sich anmelden und Befehle für dieses Projekt ausführen.

## Testen Sie Ihren Webhook lokal

Verwenden Sie die CLI, um Ereignisse an Ihren lokalen Webhook-Endpoint weiterzuleiten.

Angenommen, Ihre Anwendung läuft auf Port 4242:

```bash
stripe listen --forward-to http://localhost:4242/webhook
```

Lösen Sie in einem separaten Datenterminal-Tab ein simuliertes Ereignis aus:

```bash
stripe trigger v1.billing.meter.error_report_triggered
```

Die folgende Ausgabe erscheint in Ihrem `listen`-Tab:

```bash
[200 POST] OK v1.billing.meter.error_report_triggered
```

Ihr Server protokolliert `Meter error for:` gefolgt vom Anzeigenamen des Zählers in dem Datenterminal, in dem er ausgeführt wird.

Wenn Sie stattdessen dem Beispiel für Snapshot-Ereignisse folgen, lösen Sie `payment_intent.succeeded` aus und Ihr Server protokolliert `PaymentIntent was successful!` (PaymentIntent war erfolgreich).

## Optional: Webhook-Signatur prüfen

Stripe fügt im Header `Stripe-Signature` jedes Ereignisses eine Signatur ein, damit Sie verifizieren können, dass die Anfrage von Stripe stammt. Für Thin-Ereignisse verarbeitet `parseEventNotification()` die Signaturverifizierung automatisch. Für Snapshot-Ereignisse verwenden Sie `constructEvent()` mit drei Parametern:

- `requestBody`: Der rohe Anfragetext-String von Stripe.
- `signature`: Der Header-Wert der `Stripe-Signature`.
- `endpointSecret`: das mit Ihrem Endpoint verknüpfte Geheimnis

Finden Sie zunächst Ihr Webhook-Endpoint-Geheimnis. Wenn Sie lokal mit der Stripe-CLI testen, rufen Sie es aus der CLI-Ausgabe ab, wenn Sie `stripe listen` ausführen. Wenn Sie einen über das Dashboard verwalteten Endpoint verwenden, öffnen Sie den Endpoint in [Workbench](https://dashboard.stripe.com/workbench/webhooks) und klicken Sie auf **Geheimnis anzeigen**. Das Geheimnis beginnt mit `whsec_`.

#### Ruby

```ruby
require 'stripe'
require 'sinatra'

# If you are testing your webhook locally with the Stripe CLI you
# can find the endpoint's secret by running `stripe listen`
# Otherwise, find your endpoint's secret in your webhook settings in
# the Developer Dashboard
endpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

post '/my/webhook/url' do
  payload = request.body.read
  sig_header = request.env['HTTP_STRIPE_SIGNATURE']
  event = nil

  begin
    event = Stripe::Webhook.construct_event(
      payload, sig_header, endpoint_secret
    )
  rescue JSON::ParserError => e
    # Invalid payload
    puts "Error parsing payload: #{e.message}"
    status 400
    return
  rescue Stripe::SignatureVerificationError => e
    # Invalid signature
    puts "Error verifying webhook signature: #{e.message}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    puts 'PaymentIntent was successful!'
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    puts 'PaymentMethod was attached to a Customer!'
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end
```

Konfigurieren Sie zusätzlich zur Signaturverifizierung Ihren Server oder Ihre Firewall so, dass nur Webhook-Anfragen von den [IP-Adressen](https://docs.stripe.com/ips.md) von Stripe akzeptiert werden.

Hilfe bei Signaturfehlern finden Sie unter [Webhook-Endpoints verwalten](https://docs.stripe.com/events/manage-webhook-endpoints.md#signature-errors).

## Ihren Ereignis-Handler bereitstellen

Wenn Sie bereit für den Wechsel in die Produktionsumgebung sind:

1. Erstellen Sie einen [eingeschränkten API-Schlüssel](https://docs.stripe.com/keys.md#create-restricted-api-key) für den [Live-Modus](https://docs.stripe.com/keys.md#test-live-modes) mit nur den Berechtigungen, die Ihr Handler benötigt, wie z. B. Lesezugriff auf die Ressourcen, die Sie mit `fetchRelatedObject()` oder `fetchEvent()` abrufen.
2. Öffnen Sie [Workbench](https://dashboard.stripe.com/workbench) und navigieren Sie zum Tab **Webhooks**.
3. Klicken Sie auf **Ziel hinzufügen**.
4. Geben Sie die spezifischen Ereignistypen ein, die Sie empfangen möchten. Wählen Sie für Snapshot-Ziele außerdem die API-Version aus. Klicken Sie auf **Weiter**.
5. Wählen Sie **Webhook-Endpoint** aus der Liste der Zieltypen aus. Klicken Sie auf **Weiter**.
6. Geben Sie die URL Ihres Endpoints zusammen mit einem optionalen Namen und einer Beschreibung ein. Klicken Sie auf **Ziel erstellen**.
7. Kopieren Sie das in der Ansicht mit den Zieldetails angezeigte Endpoint-Geheimnis und verwenden Sie es anstelle des Platzhalters `whsec_...`.

Ihr Ereignis-Handler wird auf Ihrem Server ausgeführt und erfordert daher einen eingeschränkten Schlüssel oder einen Geheimschlüssel. Ein veröffentlichbarer Schlüssel kann die API-Aufrufe, die `fetchRelatedObject()` und `fetchEvent()` durchführen, nicht autorisieren.

Betten Sie den API-Schlüssel oder das Endpoint-Geheimnis nicht in Quellcode oder clientseitige Anwendungen ein. Verwenden Sie stattdessen den Secrets-Vault (Geheimnistresor) Ihrer Server-Plattform, um sie Ihrer Anwendung zur Verfügung zu stellen. Wenn Ihre Plattform keinen Secrets-Vault anbietet, legen Sie sie in den Umgebungsvariablen fest. Weitere Informationen finden Sie unter [Best Practices für API-Schlüssel](https://docs.stripe.com/keys-best-practices.md).

Ihre Anwendung ist nun bereit, Live-Ereignisse zu akzeptieren. Weitere Informationen zum Konfigurieren eines Webhook-Endpoints finden Sie unter [Webhook Endpoint API](https://docs.stripe.com/api/webhook_endpoints.md).