Zum Hauptinhalt springen

Stripe-Webhook einrichten

Wenn du Stripe über Connect with Stripe verbunden hast, führt dich diese Seite durch den einen manuellen Schritt, den Stripe danach verlangt: einen Webhook-Endpunkt selbst in deinem eigenen Stripe-Dashboard anlegen — Bildschirm für Bildschirm.

Bevor du beginnst​

  • Das gilt nur für Connect with Stripe. Wenn du Stripe verbunden hast, indem du selbst deinen Geheimschlüssel und Öffentlichen Schlüssel eingegeben hast (siehe Zahlungen — Stripe verbinden), registriert Agon den Webhook automatisch für dich — diese Seite brauchst du dann nicht.
  • Warum du das selbst tun musst: Stripe lässt ein per OAuth („Connect“) verbundenes Konto keine Webhook-Endpunkte automatisch registrieren — das ist eine Einschränkung auf Stripes Seite, keine Beschränkung von Agon. Du musst es nur einmal tun.
  • Halte die Webhook-URL deines Studios bereit. Sie wird in Agon unter Einstellungen → Abrechnung angezeigt und sieht so aus: https://studio-<deine-studio-id>.agon-studio.dev/api/billing/webhook — einzigartig für dein Studio. Lass diese Seite in einem anderen Fenster oder Tab offen, damit du sie in Schritt 7 kopieren kannst.

Schritte​

  1. Öffne dein Stripe-Dashboard und gehe zu Developers → Webhooks — oder direkt zu Workbench → Webhooks.

  2. Klicke auf Add destination.

    Stripe-Workbench-Webhooks-Seite mit der Schaltfläche Add destination

  3. Stripe öffnet einen dreistufigen Assistenten Create an event destination: Select events → Choose destination type → Configure your destination.

  4. Wähle unter Select events bei Event destination scope die Option Your account — nicht Connected accounts, das ist nur für Plattformen gedacht, die Ereignisse aus den Stripe-Konten anderer Personen empfangen. Dein Studio ist dieses Konto. Lass unter Payload style Snapshot ausgewählt — nicht Thin; Agon benötigt das vollständige Event-Objekt, nicht nur eine id, die anschließend abgerufen werden müsste. Lass API version auf dem von Stripe vorgeschlagenen Standardwert.

    Configure your event destination: Your account und Snapshot ausgewählt

  5. Nutze weiterhin unter Select events das Suchfeld Find event by name or description… — deutlich schneller als den gesamten Kategoriebaum zu durchsuchen — und markiere genau diese 6 Ereignisse, eines nach dem anderen:

    • checkout.session.completed
    • customer.subscription.created
    • customer.subscription.updated
    • customer.subscription.deleted
    • invoice.paid
    • invoice.payment_failed

    Ereignis-Suchfeld: Find event by name or description

    Sobald alle 6 markiert sind, klicke auf Continue.

  6. Wähle unter Choose destination type die Option Webhook endpoint — die erste Option. Die beiden anderen, Amazon EventBridge und Azure Event Grid, dienen dazu, Ereignisse an deine eigene Cloud-Infrastruktur weiterzuleiten, und sind hier nicht relevant. Klicke auf Continue.

    Choose destination type mit ausgewähltem Webhook endpoint

  7. Unter Configure your destination zeigt Stripe eine Zusammenfassung deiner Auswahl (Events from: Your account, Payload style: Snapshot, Listening to: 6 events), gefolgt von drei Feldern:

    • Destination name — optional, jeder Name funktioniert (zum Beispiel „Agon“). Dient nur als eigene Referenz in deinem Stripe-Dashboard und hat keine funktionale Auswirkung.
    • Endpoint URL — füge hier die Webhook-URL deines Studios von Agons Seite Einstellungen → Abrechnung ein, genau wie angezeigt. Tippe sie nicht von Hand ab — schon ein einziger Tippfehler bedeutet, dass Stripe dein Studio nie erreichen kann.
    • Description — optional, kann leer bleiben.

    Klicke auf die Schaltfläche, um das Ziel zu erstellen.

    Configure destination mit den Feldern Destination name, Endpoint URL und Description

  8. Stripe zeigt nun ein Signing secret für dein neues Ziel, manchmal hinter einem „reveal“-Element versteckt, das du zuerst anklicken musst. Kopiere es.

  9. Gehe in Agon zu Einstellungen → Abrechnung und füge es in das Feld Webhook-Geheimnis ein — dasselbe Feld, das in Zahlungen — Stripe verbinden beschrieben wird, auf dieser Seite immer sichtbar und nicht hinter einer zusätzlichen Option versteckt. Klicke auf Speichern.

Was tun, wenn etwas schiefgeht?​

Ich weiß nicht, ob ich „Your account“ oder „Connected accounts“ wählen soll

Wähle Your account. Dein Studio ist das Stripe-Konto, das du konfigurierst — Connected accounts gilt nur, wenn du eine Plattform wärst, die Ereignisse aus den separaten Stripe-Konten anderer Personen empfängt, was hier nicht der Fall ist.

Meine Zahlungen zeigen nach dieser Einrichtung weiterhin Ausstehend

Prüfe, ob die Endpoint URL exakt eingefügt wurde, ohne zusätzliche Zeichen oder fehlende Abschnitte, und ob das in Einstellungen → Abrechnung gespeicherte Webhook-Geheimnis mit dem von Stripe für dieses konkrete Ziel angezeigten Signing Secret übereinstimmt. Siehe auch Zahlungen — Was tun, wenn etwas schiefgeht?.

Ich muss später ein Ereignis hinzufügen oder die URL ändern

Öffne das Ziel erneut über Workbench → Webhooks in deinem Stripe-Dashboard und bearbeite es dort. In Agon musst du nur dann etwas aktualisieren, wenn sich auch das Signing Secret ändert.

Verwandte Seiten​