# Registrieren Sie Stripe-Ereignisse in Ihrem Webhook-Endpoint

Überwachen Sie Ereignisse von Stripe auf Ihrem Webhook-Endpoint, damit Ihre Integration automatisch Reaktionen auslösen kann.

## Start here: Install agent skills

Stripe recommends using official skills to integrate with the API using best practices. Follow the instructions below to learn how.

**Tip: Use curl instead of Fetch tools.** Skills are detailed 10–20 KB markdown files. Fetch tools summarize them. `curl -sL` guarantees the full content.

**Using `npx skills`**: Check if `npx` is installed on the system. If `npx` is available, run `npx skills add https://docs.stripe.com --list` to list available skills, then run `npx skills add https://docs.stripe.com --yes --skill <skill-name> <--skill other-skills>` to install individual skills.

**If `npx skills` isn’t available**: You can use curl to fetch the index of available skills, what they do, and their files from `https://docs.stripe.com/.well-known/skills/index.json`. To download a skill and its related files, use curl to download them from `https://docs.stripe.com/.well-known/skills/<filepath>`.

For this article, we recommend using these skills: `stripe-best-practices`

> #### Senden Sie Ereignisse an Ihr AWS-Konto oder Ihr Azure-Abonnement
> 
> Sie können Ereignisse direkt an [Amazon EventBridge](https://docs.stripe.com/event-destinations/eventbridge.md) oder [Azure Event Grid](https://docs.stripe.com/event-destinations/eventgrid.md) als Ereignisziele senden.

Erstellen Sie ein Ereignisziel, um Ereignisse an einem HTTPS-Webhook-Endpoint zu empfangen. Nach der Registrierung eines Webhook-Endpoints kann Stripe Ereignisdaten in Echtzeit an den Webhook-Endpoint Ihrer Anwendung senden, wenn in Ihrem Stripe-Konto [Ereignisse](https://docs.stripe.com/event-destinations.md#events-overview) stattfinden. Stripe verwendet HTTPS, um Webhook-Ereignisse als JSON-Nutzlast, die ein [Ereignisobjekt](https://docs.stripe.com/api/events.md) enthält, an Ihre App zu senden.

Der Empfang von Webhook-Ereignissen hilft Ihnen, auf asynchrone Ereignisse zu reagieren, z.B. wenn die Bank eines Kunden/einer Kundin eine Zahlung bestätigt, ein Kunde/eine Kundin eine Zahlungsanfechtung einleitet oder eine wiederkehrende Zahlung erfolgreich ist.

## Loslegen

So empfangen Sie Webhook-Ereignisse in Ihrer App:

1. Erstellen Sie einen Webhook-Endpoint-Handler, um POST-Anfragen für Ereignisdaten zu empfangen.
1. Testen Sie Ihren Webhook-Endpoint-Handler lokal mit der Stripe CLI.
1. Erstellen Sie ein neues [Ereignisziel](https://docs.stripe.com/event-destinations.md) für Ihren Webhook-Endpoint.
1. Sichern Sie Ihren Webhook-Endpoint.

Sie können einen Endpoint registrieren und erstellen, um mehrere verschiedene Ereignistypen auf einmal zu verarbeiten, oder individuelle Endpoints für bestimmte Ereignisse einrichten.

## Nicht unterstütztes Ereignistypverhalten für Organisationsereignisziele

Stripe sendet die meisten Ereignistypen asynchron, wartet aber bei einigen Ereignistypen auf eine Antwort. In diesen Fällen verhält sich Stripe unterschiedlich, je nachdem, ob das Ereignisziel antwortet oder nicht.

Wenn Ihr Ereignisziel [Organisations-](https://docs.stripe.com/get-started/account/orgs.md)Ereignisse empfängt, besitzen diejenigen, die eine Antwort erfordern, die folgenden Einschränkungen:

- Sie können `issuing_authorization.request` für Organisationsziele nicht abonnieren. Richten Sie stattdessen einen [Webhook-Endpoint](https://docs.stripe.com/webhooks.md#example-endpoint) in einem Stripe-Konto innerhalb der Organisation ein, um diesen Ereignistyp zu abonnieren. Verwenden Sie `issuing_authorization.request`, um Kaufanfragen in Echtzeit zu autorisieren.
- Organisationsziele, die `checkout_sessions.completed` empfangen, können nicht [mit dem Weiterleitungsverhalten](https://docs.stripe.com/checkout/fulfillment.md#redirect-hosted-checkout) umgehen, wenn Sie [Checkout](https://docs.stripe.com/payments/checkout.md) direkt in Ihre Website einbetten oder Kunden/Kundinnen auf eine von Stripe gehostete Bezahlseite umleiten. Um das Weiterleitungsverhalten von Checkout zu beeinflussen, verarbeiten Sie diesen Ereignistyp mit einem [Webhook Endpoint](https://docs.stripe.com/webhooks.md#example-endpoint), der in einem Stripe-Konto innerhalb der Organisation konfiguriert ist.
- Organisationsziele, die erfolglos auf ein `invoice.created`-Ereignis reagieren, können den [automatischen Rechnungsabschluss nicht beeinflussen, wenn Sie den automatischen Einzug](https://docs.stripe.com/billing/subscriptions/webhooks.md#understand) verwenden. Sie müssen diesen Ereignistyp mit einem [Webhook-Endpoint](https://docs.stripe.com/webhooks.md#example-endpoint) verarbeiten, der in einem Stripe-Konto innerhalb der Organisation konfiguriert ist, um den automatischen Abschluss der Rechnung auszulösen.

## Handler erstellen

Richten Sie eine HTTP- oder HTTPS-Endpoint-Funktion ein, die Webhook-Anfragen mit einer POST-Methode akzeptieren kann. Wenn Sie noch dabei sind, Ihre Endpoint-Funktion auf Ihrem lokalen Computer zu entwickeln, kann HTTP für diese verwendet werden. Nachdem sie öffentlich zugänglich ist, muss Ihre Webhook-Endpoint-Funktion HTTPS nutzen.

Richten Sie Ihre Endpoint-Funktion wie folgt ein:

- POST-Anfragen mit einer JSON-Nutzlast verarbeitet, die aus einem [Ereignisobjekt](https://docs.stripe.com/api/events/object.md) besteht.
- Für [Organisations-](https://docs.stripe.com/get-started/account/orgs.md)Ereignis-Handler wird der Wert `context` untersucht, um festzustellen, welches Konto in einem Unternehmen das Ereignis erzeugt hat, und dann der Header `Stripe-Context` entsprechend dem Wert `context` festgelegt.
- Gibt schnell einen erfolgreichen Statuscode (`2xx`) zurück, bevor eine komplexe Logik angewendet wird, die eine Zeitüberschreitung verursachen könnte. Beispielsweise müssen Sie eine `200`-Antwort zurückgeben, bevor Sie eine Kundenrechnung in Ihrem Buchhaltungssystem als bezahlt aktualisieren können.

> - Verwenden Sie unseren [interaktiven Webhook-Endpoint-Builder](https://docs.stripe.com/webhooks/quickstart.md), um eine Webhook-Endpoint-Funktion in Ihrer Programmiersprache zu erstellen.
- Verwenden Sie die Stripe-API-Referenz, um die [Thin-Event-Objekte](https://docs.stripe.com/api/v2/core/events/event-types.md) oder [Snapshot-Event-Objekte](https://docs.stripe.com/api/events/object.md) zu identifizieren, die Ihr Webhook-Handler verarbeiten muss.

#### Beispiel-Endpoint

Bei diesem Codeausschnitt handelt es sich um eine Webhook-Funktion, die so konfiguriert ist, dass sie nach empfangenen Ereignissen sucht, das Ereignis verarbeitet und eine `200`-Antwort zurückgibt. Verweisen Sie auf den [Snapshot](https://docs.stripe.com/event-destinations.md#events-overview)-Ereignis-Handler, wenn Sie API v1-Ressourcen verwenden, und verweisen Sie auf den [Thin](https://docs.stripe.com/event-destinations.md#events-overview)-Ereignis-Handler, wenn Sie API v2-Ressourcen verwenden.

#### Snapshot-Ereignis-Handler

Wenn Sie einen Snapshot-Ereignis-Handler erstellen, verwenden Sie die API-Objektdefinition zum Zeitpunkt des Ereignisses für Ihre Logik, indem Sie auf die `data.object`-Felder des Ereignisses zugreifen. Sie können die API-Ressource auch von der Stripe API abrufen, um auf die neueste und aktuellste Objektdefinition zuzugreifen.

#### Ruby

```ruby
require 'json'

# Replace this endpoint secret with your unique endpoint secret key
# If you're testing with the CLI, run 'stripe listen' to find the secret key
# If you defined your endpoint using the API or the Dashboard, check your webhook settings for your endpoint secret: https://dashboard.stripe.com/webhooks
endpoint_secret = 'whsec_...';

# Using Sinatra
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

  # Check that you have configured webhook signing
  if endpoint_secret
    # Retrieve the event by verifying the signature using the raw body and the endpoint secret
    signature = request.env['HTTP_STRIPE_SIGNATURE'];
    begin
      event = Stripe::Webhook.construct_event(
        payload, signature, endpoint_secret
      )
    rescue Stripe::SignatureVerificationError => e
      puts "⚠️  Webhook signature verification failed. #{e.message}"
      status 400
    end
  end

  # Handle the event
  case event.type
  when 'payment_intent.succeeded'
    payment_intent = event.data.object # contains a Stripe::PaymentIntent
    # Then define and call a method to handle the successful payment intent.
    # handle_payment_intent_succeeded(payment_intent)
  when 'payment_method.attached'
    payment_method = event.data.object # contains a Stripe::PaymentMethod
    # Then define and call a method to handle the successful attachment of a PaymentMethod.
    # handle_payment_method_attached(payment_method)
  # ... handle other event types
  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end
```

#### Thin-Ereignishandler (Clover+)

Wenn Sie einen Thin-Eventhandler erstellen, verwenden Sie die `fetchRelatedObject()`-Methode, um die neueste Version des mit dem Ereignis verbundenen Objekts abzurufen. Ereignisse können [zusätzliche Daten](https://docs.stripe.com/event-destinations.md#fetch-data) enthalten, die Sie nur über die Instanzmethode `.fetchEvent()` in `EventNotification` abrufen können. Die genaue Form dieser Daten hängt vom `type` des Ereignisses ab.

Ereignistypen müssen zum Zeitpunkt der Veröffentlichung verfügbar sein, um Klassen in dieser SDK-Version zu generieren. Um Ereignisse zu verarbeiten, für die das SDK keine Klassen hat, verwenden Sie die `UnknownEventNotification`-Klasse.

#### Python

```python
import os
from stripe import StripeClient
from stripe.events import UnknownEventNotification

from flask import Flask, request, jsonify

app = Flask(__name__)
api_key = os.environ.get("STRIPE_API_KEY", "")
webhook_secret = os.environ.get("WEBHOOK_SECRET", "")

client = StripeClient(api_key)

@app.route("/webhook", methods=["POST"])
def webhook():
    webhook_body = request.data
    sig_header = request.headers.get("Stripe-Signature")

    try:
        event_notif = client.parse_event_notification(
            webhook_body, sig_header, webhook_secret
        )

        # type checkers will narrow the type based on the `type` property
        if event_notif.type == "v1.billing.meter.error_report_triggered":
            # in this block, event_notification is typed as
            # a V1BillingMeterErrorReportTriggeredEventNotification

            # there's basic info about the related object in the notification
            print(f"Meter w/ id {event_notif.related_object.id} had a problem")

            # or you can fetch the full object form the API for more details
            meter = event_notif.fetch_related_object()
            print(
                f"Meter {meter.display_name} ({meter.id}) had a problem"
            )

            # And you can always fetch the full event:
            event = event_notif.fetch_event()
            print(f"More info: {event.data.developer_message_summary}")

        elif event_notif.type == "v1.billing.meter.no_meter_found":
            # in this block, event_notification is typed as
            # a V1BillingMeterNoMeterFoundEventNotification

            # that class doesn't define `fetch_related_object` because the event
            # has no related object.
            # so this line would correctly give a type error:
            # meter = event_notif.fetch_related_object()

            # but fetching the event always works:
            event = event_notif.fetch_event()
            print(
                f"Err! No meter found: {event.data.developer_message_summary}"
            )

        # Events that were introduced after this SDK version release are
        # represented as `UnknownEventNotification`s.
        # They're valid, the SDK just doesn't have corresponding classes for them.
        # You must match on the "type" property instead.
        elif isinstance(event_notif, UnknownEventNotification):
            # these lines are optional, but will give you more accurate typing in this block
            from typing import cast

            event_notif = cast(UnknownEventNotification, event_notif)

            # continue matching on the type property
            # from this point on, the `related_object` property _may_ be None
            # (depending on the event type)
            if event_notif.type == "some.new.event":
                # if this event type has a related object, you can fetch it
                obj = event_notif.fetch_related_object()
                # otherwise, `obj` will just be `None`
                print(f"Related object: {obj}")

                # you can still fetch the full event, but it will be untyped
                event = event_notif.fetch_event()
                print(f"New event: {event.data}")  # type: ignore

        return jsonify(success=True), 200
    except Exception as e:
        return jsonify(error=str(e)), 400
```

#### Thin-Ereignishandler (Acacia oder Basil)

Wenn Sie einen Thin-Ereignis-Handler erstellen, verwenden Sie die Methode `fetchRelatedObject()`, um die neueste Version des mit dem Ereignis verknüpften Objekts abzurufen. Thin-Ereignisse können [zusätzliche Kontextdaten](https://docs.stripe.com/event-destinations.md#fetch-data) enthalten, die Sie nur mit der API abrufen können. Verwenden Sie den Aufruf `retrieve()` mit der Thin-Ereignis-ID, um auf diese zusätzlichen Nutzlastfelder zuzugreifen.

#### Python

```python
import os
from stripe import StripeClient
from stripe.events import V1BillingMeterErrorReportTriggeredEvent

from flask import Flask, request, jsonify

app = Flask(__name__)
api_key = os.environ.get('STRIPE_API_KEY')
webhook_secret = os.environ.get('WEBHOOK_SECRET')

client = StripeClient(api_key)

@app.route('/webhook', methods=['POST'])
def webhook():
    webhook_body = request.data
    sig_header = request.headers.get('Stripe-Signature')

try:
    thin_event = client.parse_thin_event(webhook_body, sig_header, webhook_secret)

    # Fetch the event data to understand the failure
    event = client.v2.core.events.retrieve(thin_event.id)
    if isinstance(event, V1BillingMeterErrorReportTriggeredEvent):
        meter = event.fetch_related_object()
        meter_id = meter.id

        # Record the failures and alert your team
        # Add your logic here

    return jsonify(success=True), 200
except Exception as e:
    return jsonify(error=str(e)), 400

if __name__ == '__main__':
    app.run(port=4242)
```

#### Verwendet `context`

#### Snapshot-Ereignisse

Dieser Codeausschnitt ist eine Webhook-Funktion, die so konfiguriert ist, dass sie nach empfangenen Ereignissen sucht, das Ursprungskonto gegebenenfalls erkennt, das Ereignis verarbeitet und eine `200`-Antwort zurückgibt.

#### Ruby

```ruby
require 'json'

# Using Sinatra
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

  # Extract the context
  context = event.context

  # Define your API key variables (ideally loaded securely)
  ACCOUNT_123_API_KEY = "sk_test_123"
  ACCOUNT_456_API_KEY = "sk_test_456"

  account_api_keys = {
    "account_123" => ACCOUNT_123_API_KEY,
    "account_456" => ACCOUNT_456_API_KEY
  }

  api_key = account_api_keys[context]

  if api_key.nil?
    puts "No API key found for context: #{context}"
    status 400
    return
  end

  # Handle the event
  case event.type
  when 'customer.created'
    customer = event.data.object

    begin
      latest_customer = Stripe::Customer.retrieve(
        customer.id,
        { api_key: api_key }
      )
      handle_customer_created(latest_customer, context)
    rescue => e
      puts "Error retrieving customer: #{e.message}"
      status 500
      return
    end

  when 'payment_method.attached'
    payment_method = event.data.object

    begin
      latest_payment_method = Stripe::PaymentMethod.retrieve(
        payment_method.id,
        { api_key: api_key }
      )
      handle_payment_method_attached(latest_payment_method, context)
    rescue => e
      puts "Error retrieving payment method: #{e.message}"
      status 500
      return
    end

  else
    puts "Unhandled event type: #{event.type}"
  end

  status 200
end
```

#### Thin-Ereignishandler (Clover+)

Verwenden Sie die Eigenschaft `context` von `EventNotification`, um das Konto für Ereignisse innerhalb Ihrer [Organisation](https://docs.stripe.com/get-started/account/orgs.md) zu identifizieren. Sie müssen den [Stripe-Context-Header](https://docs.stripe.com/context.md) manuell für alle API-Aufrufe festlegen, mit Ausnahme von `.fetchRelatedObject()` und `.fetchEvent()`, die dies automatisch für Sie übernehmen.

#### Python

```python
org_api_key = os.environ.get("STRIPE_API_KEY")
webhook_secret = os.environ.get("WEBHOOK_SECRET")
client = StripeClient(org_api_key)

# inside your webhook handler
event_notification = client.parse_event_notification(payload, sig_header, webhook_secret)

# uses `context` automatically
event_notification.fetch_event()

# pass context manually for other API requests
client.v1.invoices.list(stripe_context=event_notification.context)
```

#### Thin-Ereignishandler (Acacia oder Basil)

Bei diesem Codeausschnitt handelt es sich um eine Webhook-Funktion. Sie ist so konfiguriert, dass sie Thin-Ereignisse in einer Organisation empfängt, die Signatur überprüft, mit dem Feld `context` das Ursprungskonto ermittelt und den API-Schlüssel dieses Kontos für nachfolgende API-Aufrufe verwendet.

#### Python

```python
import os
from flask import Flask, request, jsonify
from stripe import StripeClient
from stripe.events import V1BillingMeterErrorReportTriggeredEvent

app = Flask(__name__)

org_api_key = os.environ.get("STRIPE_API_KEY")
webhook_secret = os.environ.get("WEBHOOK_SECRET")
client = StripeClient(org_api_key)

account_api_keys = {
    "account_123": os.environ.get("ACCOUNT_123_API_KEY"),
    "account_456": os.environ.get("ACCOUNT_456_API_KEY"),
}

@app.route("/webhook", methods=["POST"])
def webhook():
    payload = request.data
    sig_header = request.headers.get("Stripe-Signature")

    try:
        thin_event = client.parse_thin_event(payload, sig_header, webhook_secret)

        # Retrieve the event using the org client to inspect context
        event = client.v2.core.events.retrieve(thin_event.id)

        context = getattr(event, "context", None)
        if not context:
            return jsonify(error="Missing context"), 400

        account_key = account_api_keys.get(context)
        if not account_key:
            return jsonify(error="Unknown context"), 400

        account_client = StripeClient(account_key)
        full_event = account_client.v2.core.events.retrieve(thin_event.id)

        if isinstance(full_event, V1BillingMeterErrorReportTriggeredEvent):
            meter = full_event.fetch_related_object()
            meter_id = meter.id
            # Record the failures and alert your team
            # Add your logic here

        return jsonify(success=True), 200
    except Exception as e:
        return jsonify(error=str(e)), 400

if __name__ == "__main__":
    app.run(port=4242)
```

## Handler testen

Bevor Sie mit Ihrer Webhook-Endpoint-Funktion live gehen, empfehlen wir Ihnen, Ihre Anwendungsintegration zu testen. Konfigurieren Sie dazu einen lokalen Listener zum Senden von Ereignissen an Ihren lokalen Computer und senden Sie Testereignisse. Zum Testen müssen Sie die [CLI](https://docs.stripe.com/stripe-cli.md) verwenden.

#### Ereignisse an einen lokalen Endpoint weiterleiten

Um Ereignisse an Ihren lokalen Endpoint weiterzuleiten, führen Sie den folgenden Befehl mit der [CLI](https://docs.stripe.com/stripe-cli.md) aus und richten einen lokalen Listener ein. Das Flag `--forward-to` sendet alle [Stripe-Ereignisse](https://docs.stripe.com/cli/trigger#trigger-event) im in einer [Sandbox](https://docs.stripe.com/sandboxes.md) an Ihren lokalen Webhook-Endpoint. Verwenden Sie die entsprechenden CLI-Befehle unten, je nachdem, ob Sie [Thin](https://docs.stripe.com/event-destinations.md#events-overview) oder Snapshot-Ereignisse nutzen.

#### Snapshot-Ereignisse weiterleiten

Verwenden Sie den folgenden Befehl, um [Snapshot-Ereignisse](https://docs.stripe.com/event-destinations.md#events-overview) an Ihren lokalen Listener weiterzuleiten.

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

#### Thin-Ereignisse weiterleiten

Verwenden Sie den folgenden Befehl, um [Thin-Ereignisse](https://docs.stripe.com/event-destinations.md#events-overview) an Ihren lokalen Listener weiterzuleiten.

```bash
$ stripe listen --forward-thin-to localhost:4242/webhook --thin-events "*"
```

> Sie können auch die `Listen-Funktion von Stripe` ausführen, um Ereignisse in der [Stripe Shell](https://docs.stripe.com/workbench/shell.md) anzuzeigen. Allerdings können Sie keine Ereignisse von der Shell an Ihren lokalen Endpoint weiterleiten.

Zu den nützlichen Konfigurationen, die Ihnen beim Testen mit Ihrem lokalen Listener helfen, gehören die folgenden:

- Um die Verifizierung des HTTPS-Zertifikats zu deaktivieren, verwenden Sie das optionale Flag `--skip-verify`.
- Um nur bestimmte Ereignisse weiterzuleiten, verwenden Sie das optionale Flag `--events` und übergeben Sie eine durch Kommas getrennte Liste von Ereignissen.

#### Ziel-Snapshot-Ereignisse weiterleiten

Verwenden Sie den folgenden Befehl, um Ziel-Snapshot-Ereignisse an Ihren lokalen Listener weiterzuleiten.

```bash
stripe listen --events payment_intent.created,customer.created,payment_intent.succeeded,checkout.session.completed,payment_intent.payment_failed \
  --forward-to localhost:4242/webhook
```

#### Weiterleitung von Ziel-Thin-Ereignissen

Verwenden Sie den folgenden Befehl, um Ziel-Thin-Ereignisse an Ihren lokalen Listener weiterzuleiten.

```bash
stripe listen --thin-events v1.billing.meter.error_report_triggered,v1.billing.meter.no_meter_found \
  --forward-thin-to localhost:4242/webhook
```

- Um Ereignisse von dem öffentlichen Webhook-Endpoint, den Sie bereits bei Stripe registriert haben, an Ihren lokalen Webhook-Endpoint weiterzuleiten, verwenden Sie das optionale Flag `--load-from-webhooks-api`. Es lädt Ihren registrierten Endpoint, analysiert den Pfad und die registrierten Ereignisse und hängt dann den Pfad an Ihren lokalen Webhook-Endpoint im `--forward-to path` an.

#### Snapshot-Ereignisse von einem öffentlichen Webhook-Endpoint weiterleiten

Verwenden Sie den folgenden Befehl, um Snapshot-Ereignisse von einem öffentlichen Webhook-Endpoint an Ihren lokalen Listener weiterzuleiten.

```bash
stripe listen --load-from-webhooks-api --forward-to localhost:4242/webhook
```

#### Thin-Ereignisse von einem öffentlichen Webhook-Endpoint weiterleiten

Verwenden Sie den folgenden Befehl, um Thin-Ereignisse von einem öffentlichen Webhook-Endpoint an Ihren lokalen Listener weiterzuleiten.

```bash
stripe listen --load-from-webhooks-api --forward-thin-to localhost:4242/webhook
```

- Verwenden Sie zum Überprüfen von Webhook-Signaturen `{{WEBHOOK_SIGNING_SECRET}}` aus der ursprünglichen Ausgabe des Befehls „listen“.

```output
Ready! Your webhook signing secret is '{{WEBHOOK_SIGNING_SECRET}}' (^C to quit)
```

#### Auslösen von Testereignissen

Um Testereignisse zu senden, lösen Sie einen Ereignistyp aus, den Ihr Ereignisziel abonniert hat, indem Sie manuell ein Objekt im Stripe-Dashboard erstellen. Erfahren Sie, wie Sie Ereignisse mit [Stripe für VS-Code](https://docs.stripe.com/stripe-vscode.md) auslösen können.

#### Snapshot-Ereignis auslösen

Sie können den folgenden Befehl entweder in der [Stripe Shell](https://docs.stripe.com/workbench/shell.md) oder in der [Stripe-CLI](https://docs.stripe.com/stripe-cli.md) verwenden. Dieses Beispiel löst das Ereignis `payment_intent.succeeded` aus:

```bash
stripe trigger payment_intent.succeeded
Running fixture for: payment_intent
Trigger succeeded! Check dashboard for event details.
```

#### Thin-Ereignis auslösen

Du kannst folgenden Befehl in der [Stripe-CLI](https://docs.stripe.com/stripe-cli.md). Dieses Beispiel löst ein `v1.billing.meter.error_report_triggered` Ereignis aus:

```bash
stripe trigger v1.billing.meter.error_report_triggered
Setting up fixture for: list_billing_meters
Running fixture for: list_billing_meters
Setting up fixture for: billing_meter
Running fixture for: billing_meter
Setting up fixture for: list_billing_meters_after_creation
Running fixture for: list_billing_meters_after_creation
Setting up fixture for: billing_meter_event_session
Running fixture for: billing_meter_event_session
Setting up fixture for: create_billing_meter_event_stream
Running fixture for: create_billing_meter_event_stream
Trigger succeeded! Check dashboard for event details.
```

## Ihren Endpoint registrieren

Nachdem Sie Ihre Webhook-Endpoint-Funktion getestet haben, verwenden Sie die [API](https://docs.stripe.com/api/v2/event-destinations.md) oder die Registerkarte **Webhooks** in Workbench zum Registrieren der URL Ihres Webhook-Endpoints, um sicherzustellen, dass weiß, wohin Ereignisse gesendet werden sollen. Sie können bis zu 16 Webhook-Endpoints bei Stripe registrieren. Registrierte Webhook-Endpoints müssen öffentlich zugängliche **HTTPS**-URLs sein.

#### Webhook-URL-Format

Das URL-Format zum Registrieren eines Webhook-Endpoints ist:

```
https://<your-website>/<your-webhook-endpoint>
```

Wenn Ihre Domain beispielsweise `https://mycompanysite.com` ist und die Route zu Ihrem Webhook-Endpoint `@app.route('/stripe_webhooks', methods=['POST'])` lautet, geben Sie `https://mycompanysite.com/stripe_webhooks` als **Endpoint-URL** an.

#### Ein Ereignisziel für Ihren Webhook-Endpoint erstellen

Erstellen Sie ein Ereignisziel mit Workbench im Dashboard oder programmgesteuert mit der [API](https://docs.stripe.com/api/v2/event-destinations.md). Sie können bis zu 16&nbsp;Ereignisziele für jedes Stripe-Konto registrieren.

#### Dashboard

So erstellen Sie einen neuen Webhook-Endpoint im Dashboard:

1. Öffnen Sie die Registerkarte [Webhooks](https://dashboard.stripe.com/webhooks) in Workbench.
1. Klicken Sie auf **Ereignisziel erstellen**.
1. Wählen Sie aus, von wo Sie Ereignisse empfangen möchten. Stripe unterstützt zwei Arten von Konfigurationen: **Ihr Konto** und [Verbundene Konten](https://docs.stripe.com/connect.md). Wählen Sie **Konto** aus, um Ereignisse von Ihrem eigenen Konto aus zu überwachen. Wenn Sie eine [Connect-Anwendung](https://docs.stripe.com/connect.md) erstellt haben und Ereignisse von Ihren verbundenen Konten überwachen möchten, wählen Sie **Verbundene Konten** aus.

> #### Ereignisse von einem Organisations-Webhook-Endpoint überwachen
> 
> Wenn Sie einen Webhook-Endpoint in einem [Organisationskonto](https://docs.stripe.com/get-started/account/orgs.md) erstellen, wählen Sie **Konten** aus, um Ereignisse von Konten in Ihrer Organisation zu überwachen. Wenn Ihre Organisationen [Connect-Plattformen](https://docs.stripe.com/connect.md) als Mitglieder haben und Ereignisse von allen verbundenen Konten der Plattformen überwachen möchten, wählen Sie **Verbundene Konten** aus.

1. Wählen Sie die API-Version für das [Ereignisobjekt](https://docs.stripe.com/api/events.md) aus, das Sie verwenden möchten.
1. Wählen Sie die [Ereignistypen](https://docs.stripe.com/api/events/types.md) aus, die Sie an einen Webhook-Endpoint senden möchten.
1. Wählen Sie **Weiter** und dann **Webhook-Endpoint** als Zieltyp aus.
1. Klicken Sie auf **Weiter** und geben Sie dann die **Endpoint-URL** und eine optionale Beschreibung für den Webhook ein.

#### API

Sie können ein neues Ereignisziel erstellen, das Sie über die [API](https://docs.stripe.com/api/v2/event-destinations.md) benachrichtigt, wenn ein [nutzungsbasierter](https://docs.stripe.com/billing/subscriptions/usage-based.md) Validierungsfehler in der Abrechnung ausgelöst wird.

Wenn Sie eine [Connect-Anwendung](https://docs.stripe.com/connect.md) erstellt haben und Ereignisse aus Ihren verbundenen Konten überwachen möchten, verwenden Sie den Parameter [events_from](https://docs.stripe.com/api/v2/core/event-destinations/create.md#v2_create_event_destinations-events_from) und setzen Sie dessen Wert auf `@accounts`. Für Ereignisziele vom Typ [Organisation](https://docs.stripe.com/get-started/account/orgs.md) verwenden Sie `@organization_members` für Ereignisse aus Konten in Ihrer Organisation oder `@organization_members/@accounts` für Ereignisse aus verbundenen Konten in Ihrer gesamten Organisation.

```curl
curl -X POST https://api.stripe.com/v2/core/event_destinations \
  -H "Authorization: Bearer <<YOUR_SECRET_KEY>>" \
  -H "Stripe-Version: 2026-03-25.preview" \
  --json '{
    "name": "My event destination",
    "description": "This is my event destination, I like it a lot",
    "type": "webhook_endpoint",
    "event_payload": "thin",
    "enabled_events": [
        "v1.billing.meter.error_report_triggered"
    ],
    "webhook_endpoint": {
        "url": "https://example.com/my/webhook/endpoint"
    }
  }'
```

> [Workbench](https://docs.stripe.com/workbench.md) ersetzt das bestehende [Entwickler-Dashboard](https://docs.stripe.com/development/dashboard.md). Wenn Sie immer noch das Entwickler-Dashboard verwenden, finden Sie hier weitere Informationen zum [Erstellen eines neuen Webhook-Endpoints](https://docs.stripe.com/development/dashboard/webhooks.md).

## Endpoint sichern

Nachdem Sie bestätigt haben, dass Ihr Endpoint wie erwartet funktioniert, sichern Sie ihn, indem Sie [Best Practices für Webhooks](https://docs.stripe.com/webhooks.md#best-practices) implementieren.

Sichern Ihre Integration, indem Sie dafür sorgen, dass Ihr Handler verifiziert, dass alle Webhook-Anfragen von Stripe generiert wurden. Sie können Webhook-Signaturen mit unseren offiziellen Bibliotheken verifizieren oder manuell.

#### Verifizierung mit offiziellen Bibliotheken (empfohlen)

### Webhook-Signaturen mit offiziellen Bibliotheken verifizieren

Wir empfehlen die Verwendung unserer offiziellen Bibliotheken, um Signaturen zu überprüfen. Sie führen die Verifizierung durch, indem Sie die Ereignisnutzlast, den `Stripe-Signature`-Header und das Geheimnis des Endpoints angeben. Wenn die Verifizierung fehlschlägt, erhalten Sie eine Fehlermeldung.

Wenn Sie einen Fehler bei der Signaturüberprüfung erhalten, lesen Sie unseren Leitfaden zur [Fehlerbehebung](https://docs.stripe.com/webhooks/signature.md).

> Stripe benötigt den Rohtext der Anfrage, um die Signaturprüfung durchzuführen. Wenn Sie ein Framework verwenden, müssen Sie sicherstellen, dass der Rohtext nicht manipuliert wird. Jegliche Manipulation des Rohtextes der Anfrage führt dazu, dass die Verifizierung fehlschlägt.

#### 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.
Stripe.api_key = '<<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
```

#### Manuell verifizieren

### Webhook-Signaturen manuell verifizieren

Obwohl wir empfehlen, unsere offiziellen Bibliotheken zu verwenden, um Webhook-Ereignissignaturen zu überprüfen, können Sie mithilfe dieses Abschnitts eine nutzerdefinierte Lösung erstellen.

Der `Stripe-Signature`-Header in jedem signierten Ereignis enthält einen Zeitstempel und eine oder mehrere Signaturen, die Sie überprüfen müssen. Dem Zeitstempel wird `t=` vorangestellt und jeder Signatur wird ein *Schema* vorangestellt. Schemata beginnen mit `v`, gefolgt von einer ganzen Zahl. Derzeit ist `v1` die einzige gültige Live-Signatur. Als Hilfe bei Tests sendet Stripe eine zusätzliche Signatur mit einem falschen `v0`-Schema für Ereignisse im Test-Modus.

```
Stripe-Signature:
t=1492774577,
v1=5257a869e7ecebeda32affa62cdca3fa51cad7e77a0e56ff536d0ce8e108d8bd,
v0=6ffbb59b2300aae63f272406069a9788598b792a944a07aba816edb039989a39
```

> Wir haben der Übersichtlichkeit halber neue Zeilen eingefügt, aber ein echter `Stripe-Signature`-Header befindet sich in einer einzigen Zeile.

Stripe generiert Signaturen mithilfe eines Hash-basierten Nachrichtenauthentifizierungscodes ([HMAC](https://en.wikipedia.org/wiki/Hash-based_message_authentication_code)) mit [SHA-256](https://en.wikipedia.org/wiki/SHA-2). Um [Downgrade-Angriffe](https://en.wikipedia.org/wiki/Downgrade_attack) zu verhindern, ignorieren Sie alle Schemata, die nicht `v1` sind.

Sie können mehrere Signaturen mit demselben Schema-Geheimschlüssel-Paar haben, wenn Sie den [Geheimschlüssel eines Endpoints neu generieren](https://docs.stripe.com/webhooks.md#roll-endpoint-secrets) und den vorherigen Geheimschlüssel bis zu 24&nbsp;Stunden aktiv lassen. Während dieses Zeitraums verfügt Ihr Endpoint über mehrere aktive Geheimschlüssel und Stripe generiert für jeden dieser Geheimschlüssel eine Signatur.

Um eine manuelle Lösung zum Verifizieren von Signaturen zu erstellen, müssen Sie die folgenden Schritte ausführen:

#### Schritt 1: Entfernen Sie den Zeitstempel und die Signaturen aus der Kopfzeile

Teilen Sie die Kopfzeile mit dem Zeichen `,` auf, um eine Liste der Elemente zu erhalten. Teilen Sie dann jedes Element mit dem Zeichen `=` als Trennzeichen auf, um ein Präfix und ein Wertpaar zu erhalten.

Der Wert des Präfixes `t` entspricht dem Zeitstempel und `v1` entspricht der Signatur (oder den Signaturen). Sie können alle anderen Elemente verwerfen.

#### Schritt 2: Bereiten Sie die Zeichenfolge `signed_payload` vor

Die Zeichenfolge `signed_payload` wird durch Verketten folgender Elemente erstellt:

- Zeitstempel (als Zeichenfolge)
- Das Zeichen `.`
- Die tatsächliche JSON-Nutzlast (also der Anfragetext)

#### Schritt 3: Die erwartete Signatur ermitteln

Berechnen Sie einen HMAC mit der SHA256-Hash-Funktion. Verwenden Sie den Signatur-Geheimschlüssel des Endpoints als Schlüssel und die Zeichenfolge `signed_payload` als Nachricht.

#### Schritt 4: Vergleichen Sie die Signaturen

Vergleichen Sie die Signatur (oder Signaturen) in der Kopfzeile. Für eine identische Übereinstimmung, berechnen Sie die Differenz zwischen dem aktuellen und dem empfangenen Zeitstempel und entscheiden Sie dann, ob die Differenz in Ihrem Toleranzbereich liegt.

Zum Schutz vor Timing-Angriffen verwenden Sie einen konstanten Zeit-String-Vergleich, um die erwartete Signatur mit jeder der empfangenen Signaturen zu vergleichen.

## Webhook-Integrationen debuggen

Bei der Übermittlung von Ereignissen an Ihren Webhook-Endpoint können mehrere Arten von Problemen auftreten:

- Stripe kann ein Ereignis möglicherweise nicht an Ihren Webhook-Endpoint übermitteln.
- Bei Ihrem Webhook-Endpoint besteht möglicherweise ein SSL-Problem.
- Ihre Netzwerkverbindung ist unterbrochen.
- Ihr Webhook-Endpoint empfängt die von Ihnen erwarteten Ereignisse nicht.

### Ereignisübermittlungen anzeigen

Um die Zustellungen von Events anzuzeigen, wählen Sie den Webhook-Endpoint unter **Webhooks** aus und klicken Sie anschließend auf die Registerkarte **Events**. Auf der Registerkarte **Events** finden Sie eine Liste der Events und den Status `Delivered`, `Pending` oder `Failed`. Klicken Sie auf ein Event, um die Metadaten anzuzeigen, darunter den HTTP-Statuscode des Zustellversuchs und den Zeitpunkt ausstehender zukünftiger Zustellungen.

Sie können auch die [Stripe-CLI](https://docs.stripe.com/stripe-cli.md) verwenden, um direkt in Ihrem Datenterminal [Ereignisse zu überwachen](https://docs.stripe.com/webhooks.md#test-webhook).

### HTTP-Statuscodes korrigieren

Wenn ein Ereignis den Statuscode `200` anzeigt, bedeutet dies eine erfolgreiche Zustellung an den Webhook-Endpoint. Möglicherweise erhalten Sie auch einen anderen Statuscode als `200`. In der folgenden Tabelle finden Sie eine Liste gängiger HTTP-Statuscodes und empfohlener Lösungen.

| Webhook-Status ausstehend                    | Beschreibung                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Korrigieren                                                                                                                                                 |
| -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| (Verbindung nicht möglich) FHLR              | Wir können keine Verbindung zum Zielserver herstellen.                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Stellen Sie sicher, dass Ihre Host-Domain im Internet öffentlich zugänglich ist.                                                                            |
| (`302`) FHLR (oder ein anderer `3xx`-Status) | Der Zielserver hat versucht, die Anfrage an einen anderen Standort umzuleiten. Wir betrachten Weiterleitungsantworten auf Webhook-Anfragen als fehlgeschlagen.                                                                                                                                                                                                                                                                                                                                              | Legen Sie das Webhook-Endpoint-Ziel auf die durch die Weiterleitung aufgelöste URL fest.                                                                    |
| (`400`) FHLR (oder ein anderer `4xx`-Status) | Der Zielserver kann oder wird die Anfrage nicht verarbeiten. Dies kann vorkommen, wenn der Server einen Fehler erkennt (`400`), wenn für die Ziel-URL Zugriffsbeschränkungen gelten (`401`, `403`) oder wenn die Ziel-URL nicht existiert (`404`).                                                                                                                                                                                                                                                          | - Stellen Sie sicher, dass Ihr Endpoint im Internet öffentlich zugänglich ist.
  - Stellen Sie sicher, dass Ihr Endpoint eine POST-HTTP-Methode akzeptiert. |
| (`500`) FHLR (oder ein anderer `5xx`-Status) | Bei der Verarbeitung der Anfrage ist auf dem Zielserver ein Fehler aufgetreten.                                                                                                                                                                                                                                                                                                                                                                                                                             | Überprüfen Sie die Protokolle Ihrer Anwendung, um zu verstehen, warum der Fehler `500` zurückgegeben wird.                                                  |
| (TLS-Fehler) FHLR                            | Wir konnten keine sichere Verbindung zum Zielserver herstellen. Diese Fehler werden in der Regel durch Probleme mit dem SSL/TLS-Zertifikat oder einem Zwischenzertifikat in der Zertifikatskette des Zielservers verursacht. Stripe erfordert die *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol)-Version `v1.2` oder neuer. | Führen Sie einen [SSL-Servertest](https://www.ssllabs.com/ssltest/) durch, um Probleme zu finden, die diesen Fehler möglicherweise verursacht haben.        |
| (Zeit überschritten) FHLR                    | Die Antwort des Zielservers auf die Webhook-Anfrage dauerte zu lange.                                                                                                                                                                                                                                                                                                                                                                                                                                       | Stellen Sie sicher, dass Sie komplexe Logik zurückstellen und sofort eine erfolgreiche Antwort in Ihrem Webhook-Verarbeitungscode zurückgeben.              |

## Verhaltensweisen der Ereignisübermittlung

In diesem Abschnitt erfahren Sie, welche Verhaltensweisen Sie in Bezug auf das Senden von Ereignissen durch Stripe an Ihren Webhook-Endpoint erwarten können.

### Automatische Wiederholungsversuche

Stripe versucht, Ereignisse mit einem exponentiellen Backoff im Live-Modus bis zu drei Tage an Ihr Ziel zu senden. Wann der nächste Wiederholungsversuch stattfinden wird, sofern zutreffend, sehen Sie auf der Registerkarte **Ereignisübermittlungen** Ihres Ereignisziels. Wir versuchen, Ereignisse, die in einer Sandbox erstellt wurde, innerhalb weniger Stunden dreimal zu übermitteln. Wenn Ihr Ziel bei unserem Wiederholungsversuch deaktiviert oder gelöscht wurde, unternehmen wir keine zukünftigen Wiederholungsversuche für dieses Ereignis. Wenn Sie ein Ereignisziel jedoch deaktivieren und wieder reaktivieren, bevor wir einen erneuten Versuch starten können, sehen Sie nach wie vor zukünftige Wiederholungsversuche.

### Manuelle Wiederholungsversuche

Es gibt zwei Möglichkeiten, Ereignisse manuell zu wiederholen:

- Klicken Sie im Stripe-Dashboard auf **Erneut senden**, wenn Sie sich ein bestimmtes Ereignis ansehen. Dies funktioniert bis zu 15 Tage nach der Erstellung des Ereignisses.
- Führen Sie mit der [Stripe CLI](https://docs.stripe.com/cli/events/resend) den Befehl `stripe events resend <event_id> --webhook-endpoint=<endpoint_id>` aus. Dies funktioniert bis zu 30&nbsp;Tage nach der Erstellung des Ereignisses.

Das manuelle erneute Senden eines Ereignisses, bei dem zuvor Fehler bei der Zustellung an einen Webhook-Endpoint aufgetreten sind, hebt das [automatische Wiederholungsverhalten](https://docs.stripe.com/webhooks.md#automatic-retries) von Stripe nicht auf, selbst wenn dies zu einem `2xx`-Statuscode führt. Erfahren Sie, wie Sie [nicht zugestellte Webhook-Ereignisse verarbeiten können](https://docs.stripe.com/webhooks/process-undelivered-events.md), um zukünftige Wiederholungsversuche zu verhindern.

### Anordnung von Ereignissen

Stripe garantiert die Übermittlung von Ereignissen nicht in der Reihenfolge, in der sie generiert wurden. Beim Erstellen eines Abonnements können beispielsweise die folgenden Ereignisse generiert werden:

- `customer.subscription.created`
- `invoice.created`
- `invoice.paid`
- `charge.created` (wenn eine Zahlung vorhanden ist)

Stellen Sie sicher, dass Ihr Ereignisziel Ereignisse nicht nur in einer bestimmten Reihenfolge empfangen kann. Ihr Ziel sollte jegliche Übermittlung entsprechend verarbeiten können. Sie können fehlende Objekte auch mit der API abrufen. So können Sie beispielsweise die Objekte für Rechnung, Zahlung und Abonnement mit den Informationen aus `invoice.paid` abrufen, wenn Sie dieses Ereignis zuerst erhalten.

### API-Versionierung

Die API-Version in Ihren Kontoeinstellungen beim Auftreten des Ereignisses bestimmt die API-Version und damit die Struktur eines [Ereignisses](https://docs.stripe.com/api/events.md), das an Ihr Ziel gesendet wird. Wenn für Ihr Konto beispielsweise eine ältere API-Version festgelegt ist, z.&nbsp;B. 16.02.2015, und Sie die API-Version mit [Versionierung](https://docs.stripe.com/api.md#versioning) für eine bestimmte Anfrage ändern, basiert das generierte und an Ihr Ziel gesendete [Ereignis](https://docs.stripe.com/api/events.md)-Objekt weiterhin auf der API-Version 2015-02-16. Sie können [Ereignis](https://docs.stripe.com/api/events.md)-Objekte nach der Erstellung nicht mehr ändern. Wenn Sie beispielsweise eine Zahlung aktualisieren, bleibt das ursprüngliche Zahlungsereignis unverändert. Nachfolgende Aktualisierungen der API-Version Ihres Kontos ändern daher vorhandene [Ereignis](https://docs.stripe.com/api/events.md)-Objekte nicht rückwirkend. Auch das Abrufen eines älteren [Ereignisses](https://docs.stripe.com/api/events.md) durch Aufrufen von `/v1/events` mithilfe einer neueren API-Version wirkt sich nicht auf die Struktur des empfangenen Ereignisses aus. Sie können Testereignisziele entweder auf Ihre Standard-API-Version oder die neueste API-Version festlegen. Das an das Ziel gesendete [Ereignis](https://docs.stripe.com/api/events.md) ist für die angegebene Version des Ereignisziels strukturiert.

## Best Practices für die Verwendung von Webhooks

Überprüfen Sie diese Best Practices, um sicherzustellen, dass Ihre Webhook-Endpoints sicher bleiben und gut mit Ihrer Integration funktionieren.

### Umgang mit doppelten Ereignissen

Webhook-Endpoints empfangen gelegentlich dasselbe Ereignis mehrmals. Sie können sich vor dem Erhalt doppelter Ereignisse schützen, indem Sie Ihre verarbeiteten [Ereignis-IDs](https://docs.stripe.com/api/events/object.md#event_object-id) protokollieren und bereits protokollierte Ereignisse dann nicht erneut verarbeiten.

In einigen Fällen werden zwei separate Ereignisobjekte generiert und gesendet. Um diese Duplikate zu identifizieren, verwenden Sie die ID des Objekts in `data.object` zusammen mit dem `event.type`.

### Nur die Ereignistypen überwachen, die Ihre Integration erfordert

Konfigurieren Sie Ihre Webhook-Endpoints so, dass sie nur die für Ihre Integration erforderlichen Ereignistypen empfangen. Die Überwachung zusätzlicher Ereignisse (oder aller Ereignisse) belastet Ihren Server und wird nicht empfohlen.

Sie können [die Ereignisse](https://docs.stripe.com/api/webhook_endpoints/update.md#update_webhook_endpoint-enabled_events), die ein Webhook-Endpoint empfängt, im Dashboard oder mit der API ändern.

### Ereignisse asynchron verarbeiten

Konfigurieren Sie Ihren Handler so, dass eingehende Ereignisse mit einer asynchronen Warteschlange verarbeitet werden. Möglicherweise treten Skalierbarkeitsprobleme auf, wenn Sie sich für die synchrone Verarbeitung von Ereignissen entscheiden. Jeder große Anstieg bei den Webhook-Übermittlungen (z.&nbsp;B. zu Beginn des Monats, wenn alle Abonnements verlängert werden) kann Ihre Endpoint-Hosts überfordern.

Asynchrone Warteschlangen ermöglichen es Ihnen, die gleichzeitigen Ereignisse mit einer Geschwindigkeit zu verarbeiten, die Ihr System unterstützen kann.

### Webhook-Route vom CSRF-Schutz ausgenommen

Wenn Sie Rails, Django oder ein anderes Web-Framework verwenden, überprüft Ihre Website möglicherweise automatisch, ob jede POST-Anfrage ein *CSRF-Token* enthält. Dies ist eine wichtige Sicherheitsfunktion, die Sie und Ihre Nutzer/innen vor [Cross-Site-Request-Forgery](https://www.owasp.org/index.php/Cross-Site_Request_Forgery_\(CSRF\)) -Angriffen schützt. Diese Sicherheitsmaßnahme kann Ihre Website jedoch auch daran hindern, legitime Ereignisse zu verarbeiten. In diesem Fall müssen Sie möglicherweise die Webhooks-Route vom CSRF-Schutz ausnehmen.

#### Rails

```ruby
class StripeController < ApplicationController
  # If your controller accepts requests other than Stripe webhooks,
  # you'll probably want to use `protect_from_forgery` to add CSRF
  # protection for your application. But don't forget to exempt
  # your webhook route!
  protect_from_forgery except: :webhook

  def webhook
    # Process webhook data in `params`
  end
end
```

### Ereignisse mit einem HTTPS-Server empfangen

Wenn Sie eine HTTPS-URL für Ihren Webhook-Endpoint verwenden (im Live-Modus erforderlich), validiert Stripe, dass die Verbindung zu Ihrem Server sicher ist, bevor wir Ihre Webhook-Daten senden. Damit dies funktioniert, muss der Server so konfiguriert sein, dass er HTTPS mit einem gültigen Server-Zertifikat unterstützt. Stripe-Webhooks unterstützen nur die *TLS* (TLS refers to the process of securely transmitting data between the client—the app or browser that your customer is using—and your server. This was originally performed using the SSL (Secure Sockets Layer) protocol)-Versionen v1.2 und v1.3.

### Geheimschlüssel für Signaturen für Endpoints in regelmäßigen Abständen neu generieren

Der Geheimschlüssel, der verwendet wird, um zu überprüfen, ob Ereignisse von Stripe stammen, kann auf der Registerkarte **Webhooks** in Workbench geändert werden. Um Geheimschlüssel zu schützen, empfehlen wir sie in regelmäßigen Abständen neu zu generieren (zu ändern) oder wenn Sie vermuten, dass ein Geheimschlüssel kompromittiert wurde.

So generieren Sie einen Geheimschlüssel neu:

1. Klicken Sie auf die einzelnen Endpoints auf der Workbench-Registerkarte **Webhooks**, für die Sie den Geheimschlüssel neu generieren möchten.
1. Navigieren Sie zum Überlaufmenü (⋯) und klicken Sie auf **Geheimschlüssel neu generieren**. Sie können den aktuellen Geheimschlüssel sofort ablaufen lassen oder den Ablauf um bis zu 24&nbsp;Stunden verzögern, damit Sie Zeit haben, den Verifizierungscode auf Ihrem Server zu aktualisieren. Während dieses Zeitraums sind mehrere Geheimschlüssel für den Endpoint aktiv. Stripe generiert bis zum Ablauf eine Signatur pro Geheimschlüssel.

### Überprüfen, ob Ereignisse von Stripe gesendet werden

Ohne Verifizierung können bei einem Angriff gefälschte Webhook-Ereignisse an Ihren Endpoint gesendet werden, um Aktionen wie die Ausführung von Bestellungen, die Gewährung von Kontozugriff oder die Änderung von Datensätzen auszulösen. Überprüfen Sie immer, ob Webhook-Ereignisse von Stripe stammen, bevor Sie sie verarbeiten.

Verwenden Sie diese beiden Schutzmaßnahmen:

- **IP-Zulassungsliste**: Stripe sendet Webhook-Ereignisse von einer festgelegten Liste von [IP-Adressen](https://docs.stripe.com/ips.md). Konfigurieren Sie Ihren Server oder Ihre Firewall so, dass nur Webhook-Anfragen von diesen Adressen akzeptiert werden.
- **Signaturprüfung**: Stripe signiert jedes Webhook-Ereignis, indem es eine Signatur in den `Stripe-Signature`-Header aufnimmt. Verifizieren Sie diese Signatur mithilfe unserer [offiziellen Bibliotheken](https://docs.stripe.com/webhooks.md#verify-official-libraries) oder [manuell](https://docs.stripe.com/webhooks.md#verify-manually), um zu bestätigen, dass das Ereignis nicht von einem Dritten gesendet oder geändert wurde.

Im folgenden Abschnitt wird beschrieben, wie Sie Webhook-Signaturen verifizieren:

1. Rufen Sie den Geheimschlüssel Ihres Endpoints ab.
1. Überprüfen Sie die Signatur.

#### Geheimschlüssel Ihres Endpoints abrufen

Verwenden Sie Workbench und gehen Sie auf die Registerkarte **Webhooks**, um alle Ihre Endpoints anzuzeigen. Wählen Sie einen Endpoint aus, für den Sie den Geheimschlüssel erfahren möchten, und klicken Sie dann auf **Klicken Sie zum Aufdecken**.

Stripe generiert für jeden Endpoint einen eindeutigen Geheimschlüssel. Wenn Sie denselben Endpoint sowohl für [Test- als auch für Live-API-Schlüssel](https://docs.stripe.com/keys.md#test-live-modes) verwenden, ist der Geheimschlüssel für jeden dieser Schlüssel unterschiedlich. Wenn Sie mehrere Endpoints verwenden, müssen Sie außerdem für jeden Endpoint, für den Sie Signaturen verifizieren möchten, einen Geheimschlüssel abrufen. Nach dieser Einrichtung beginnt Stripe, jeden Webhook zu signieren, der an den Endpoint gesendet wird.

### Replay-Angriffe verhindern

Bei einem [Replay-Angriff](https://en.wikipedia.org/wiki/Replay_attack) fängt ein Angreifer eine gültige Nutzlast und deren Signatur ab und überträgt sie dann erneut. Um solche Angriffe zu verhindern, fügt Stripe einen Zeitstempel in den `Stripe-Signature`-Header ein. Da der Zeitstempel zu der signierten Nutzlast gehört, ist er ebenfalls durch die Signatur verifiziert. So kann ein Angreifer den Zeitstempel nicht ändern, ohne dass die Signatur ungültig wird. Wenn die Signatur gültig, der Zeitstempel aber zu alt ist, kann Ihre Anwendung die Nutzlast ablehnen.

Unsere Bibliotheken haben eine Standardtoleranz von 5 Minuten zwischen dem Zeitstempel und der aktuellen Zeit. Sie können diese Toleranz ändern, indem Sie bei der Überprüfung von Signaturen einen zusätzlichen Parameter angeben. Verwenden Sie das Network Time Protocol ([NTP](https://en.wikipedia.org/wiki/Network_Time_Protocol)), um sicherzustellen, dass die Uhrzeit Ihres Servers korrekt ist und mit der Zeit auf den Servern von Stripe synchronisiert wird.

> Verwenden Sie keinen Toleranzwert von `0`.Mit einem Toleranzwert von `0` wird die Aktualitätsprüfung vollständig deaktiviert.

Stripe generiert den Zeitstempel und die Signatur jedes Mal, wenn wir ein Ereignis an Ihren Endpoint senden. Wenn Stripe ein Ereignis wiederholt (zum Beispiel weil Ihr Endpoint zuvor mit einem Nicht-`2xx`-Statuscode geantwortet hat), generieren wir eine neue Signatur und einen neuen Zeitstempel für den neuen Zustellungsversuch.

### Schnelle Rückgabe einer 2xx-Antwort

Ihr [Endpoint](https://docs.stripe.com/webhooks.md#example-endpoint) muss schnell einen erfolgreichen Statuscode (`2xx`) zurückgeben, bevor eine komplexe Logik angewendet wird, die eine Zeitüberschreitung verursachen könnte. Beispielsweise müssen Sie eine `200`-Antwort zurückgeben, bevor Sie eine Kundenrechnung in Ihrem Buchhaltungssystem als bezahlt aktualisieren können.

## See also

- [Ereignisse an Amazon EventBridge senden](https://docs.stripe.com/event-destinations/eventbridge.md)
- [Senden Sie Ereignisse an Azure Event Grid](https://docs.stripe.com/event-destinations/eventgrid.md)
- [Liste der schlanken Ereignistypen](https://docs.stripe.com/api/v2/core/events/event-types.md)
- [Liste der Snapshot-Ereignistypen](https://docs.stripe.com/api/events/.md)
- [Interaktiver Generator für Webhook-Endpoints](https://docs.stripe.com/webhooks/quickstart.md)