# Handle payment events with webhooks

How to use webhooks to respond to offline payment events.

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
Weitere Installationsoptionen finden Sie unter [Mit der Stripe-CLI loslegen](https://docs.stripe.com/stripe-cli.md).
Führen Sie nach Installieren der Stripe-CLI in der Kommandozeile `stripe login` aus, um einen Kopplungscode zu generieren, der eine Verknüpfung zu Ihrem Stripe-Konto herstellt. Drücken Sie auf **Eingabe**, um Ihren Browser zu starten und sich in Ihrem Stripe-Konto anzumelden, um den Zugriff zu genehmigen. Der erstellte API-Schlüssel ist 90 Tage lang gültig. Sie können den Schlüssel unter [API-Schlüssel](https://dashboard.stripe.com/apikeys) im Dashboard ändern oder löschen.

> Sie können eine projektspezifische Konfiguration erstellen, indem Sie bei der Anmeldung und beim Ausführen von Befehlen für dieses Projekt das Flag [–project-name](https://docs.stripe.com/cli/login#login-project-name) einfügen.

Test

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

Wenn Sie einen bestehenden API-Schlüssel nutzen möchten, verwenden Sie die Markierung `--api-key`:

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

## 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 Dashboardendpoint_secret = 'whsec_...'

# Using the Sinatra framework
set :port, 4242

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

  beginevent = 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.
1. Konfigurieren Sie Ihren Webhook-Endpoint in [Workbench](https://docs.stripe.com/workbench.md) oder über die API.
1. Um Ihren Endpoint in Workbench zu konfigurieren, gehen Sie auf die Registerkarte [Webhooks](https://dashboard.stripe.com/workbench/webhooks).
1. 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**.
1. 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).