# Zahlungsereignisse mit Webhooks verarbeiten

So verwenden Sie Webhooks, um Offline-Zahlungen zu verarbeiten

Ein *Webhook* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) ist ein HTTP-Endpoint, der Ereignisse von Stripe empfängt.

Durch Webhooks können Sie unter anderem über folgende, Zahlungsereignisse außerhalb Ihres Zahlungsvorgangs benachrichtigt werden:

- Erfolgreiche Zahlungen (`payment_intent.succeeded`)
- Angefochtene Zahlungen (`charge.dispute.created`)
- Auf Ihrem Stripe-Konto verfügbares Guthaben (`balance.available`)

Während das Dashboard ideal für einmalige Aktionen wie die Rückerstattung einer Zahlung oder die Aktualisierung von Kundeninformationen geeignet ist, helfen Webhooks bei der Skalierung Ihrer Zahlungsinformationen und bei der Verarbeitung großer Mengen unternehmenskritischer Ereignisse.

## Erstellen Sie Ihren eigenen Webhook

Sie können auf Ihrem eigenen Server einen Webhook-Handler erstellen, der all Ihre Zahlungsabläufe offline verwaltet. Beginnen Sie, indem Sie einen Endpoint bereitstellen, der Anfragen von Stripe empfangen kann und verwenden Sie die CLI, um Ihre Integration lokal zu testen. Jede Anfrage von Stripe enthält ein [Ereignis](https://docs.stripe.com/api/events/object.md)-Objekt mit einer Referenz zu dem Objekt in Stripe, das geändert wurde.

## Einen Webhook-Endpoint erstellen

Fügen Sie einen neuen Endpoint in Ihrer Anwendung hinzu. Sie können auf bestimmte Ereignisse reagieren, indem Sie das Feld `type` des Ereignisses auswählen, das im Haupttext der Anfrage gesendet wurde. Dann können Sie die Standardausgabe drucken, um sich zu vergewissern, dass der Webhook funktioniert.

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

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

require 'stripe'
require 'sinatra'
require 'json'

# Using the Sinatra framework
set :port, 4242

post '/webhook' do
  payload = request.body.read
  event = nil

  begin
    event = Stripe::Event.construct_from(
      JSON.parse(payload, symbolize_names: true)
    )
  rescue JSON::ParserError => e
    # Invalid payload
    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
```

## Installieren und richten Sie die Stripe-CLI ein

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

```bash
npm install --global @stripe/cli
```

> 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.

Nach der Installation verbinden Sie die CLI mit Ihrem Stripe-Konto, indem Sie sich anmelden:

```bash
stripe login
```

Die CLI zeigt einen Kopplungscode an und öffnet das Stripe-Dashboard, in dem Sie den Zugriff auf Konten, Sandboxes und den Live-Modus genehmigen. Die CLI speichert Ihre Anmeldedaten im sicheren Anmeldedatenspeicher Ihres Betriebssystems (sofern verfügbar) und aktualisiert die Sitzung automatisch. Um sich stattdessen mit einem API-Schlüssel zu authentifizieren, führen Sie `stripe login --interactive` aus, verwenden Sie `stripe config`, übergeben Sie `--api-key` oder legen Sie die Umgebungsvariable `STRIPE_API_KEY` fest.

## Testen Sie Ihren Webhook lokal

Verwenden Sie die CLI, um Ereignisse an Ihren lokalen Webhook-Endpoint mithilfe des Befehls `listen` weiterzuleiten.

Sofern Ihre Anwendung auf dem Port 4242 ausgeführt wird, führen Sie Folgendes aus:

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

Verwenden Sie in einer anderen Terminal-Registerkarte den CLI-Befehl `trigger`, um ein Probe-Webhook-Ereignis auszulösen.

```bash
stripe trigger payment_intent.succeeded
```

Das folgende Ereignis wird in Ihrer Registerkarte `listen` angezeigt:

```bash
[200 POST] OK payment_intent.succeeded
```

„PaymentIntent war erfolgreich!“ erscheint auf der Terminal-Registerkarte, auf der Ihr Server ausgeführt wird, sehen.

## Optional: Webhook-Signatur prüfen

Stripe nimmt in die Kopfzeile `Stripe-Signature` jedes Ereignisses eine Signatur auf. So können Sie verifizieren, dass die Ereignisse von Stripe und nicht von einer Drittpartei gesendet wurden. Sie können Signaturen entweder mithilfe unserer offiziellen Bibliotheken verifizieren oder mit Ihrer eigenen Lösung [Signaturen manuell überprüfen](https://docs.stripe.com/webhooks.md#verify-manually).

Suchen Sie zunächst Ihr Webhook-Endpoint-Geheimnis und fügen Sie es Ihrem Webhook-Handler als `endpoint_secret` hinzu. Da Sie immer noch die Stripe-CLI verwenden, um unseren Endpoint lokal zu entwickeln, verwenden Sie den Befehl `trigger`, um das Webhook-Endpoint-Geheimnis von der CLI abzurufen.

```bash
stripe listen
```

Das Webhook-Endpoint-Geheimnis beginnt mit `whsec_`, gefolgt von einer Reihe von Ziffern und Buchstaben. Bewahren Sie dieses Webhook-Endpoint-Geheimnis sicher auf und machen Sie es niemals öffentlich.

#### Ruby

```ruby

# Don't put any keys in code. See https://docs.stripe.com/keys-best-practices.
# Find your keys at https://dashboard.stripe.com/apikeys.
client = Stripe::StripeClient.new('<<YOUR_SECRET_KEY>>')

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
```

## Stellen Sie Ihren Webhook-Endpoint bereit

Wenn Sie bereit sind, Ihren Webhook-Endpoint für die Produktion bereitzustellen, müssen Sie Folgendes beachten:

1. Verwenden Sie Ihre [Live-Modus-API-Schlüssel](https://docs.stripe.com/keys.md#test-live-modes), nicht Ihre Testschlüssel.
2. Konfigurieren Sie Ihren Webhook-Endpoint in [Workbench](https://docs.stripe.com/workbench.md) oder über die API.
3. Um Ihren Endpoint in Workbench zu konfigurieren, gehen Sie auf die Registerkarte [Webhooks](https://dashboard.stripe.com/workbench/webhooks).
4. Klicken Sie auf **Ziel hinzufügen** und geben Sie die Stripe-API-Version und die spezifischen Ereignisse ein, die Stripe senden soll. Klicken Sie auf **Fortfahren** und wählen Sie **Webhook-Endpoint** aus der Liste der verfügbaren Zieltypen. Klicken Sie auf **Weiter** und geben Sie die URL Ihres Endpoints, einen optionalen Namen und eine optionale Beschreibung ein. Klicken Sie auf **Ziel erstellen**.
5. Ersetzen Sie das Geheimnis für den Webhook-Endpoint in Ihrer Anwendung durch das neue Geheimnis, das in der Zielansicht in Workbench für Ihren Endpoint angezeigt wird.

Ihre Anwendung kann jetzt Live-Ereignisse empfangen. Weitere Informationen zum Konfigurieren Ihres Webhook-Endpoints finden Sie in der [Webhook Endpoint](https://docs.stripe.com/api/webhook_endpoints.md) API. Informationen zum Testen in einer Sandbox finden Sie in [unserem Entwicklungsleitfaden](https://docs.stripe.com/webhooks.md).