Den Stripe-Webhook richtig einrichten

Ohne Webhook erfährt dein Blog nie, dass ein Kauf stattgefunden hat. Der Käufer landet zwar auf deiner Danke-Seite, aber das Theme kann nicht wissen, ob die Weiterleitung aus einer echten Zahlung stammt oder ob jemand die URL auswendig geraten hat. Die Danke-Seite allein ist kein Beleg. Die einzige verlässliche Stelle, die Stripe selbst meldet „Kauf durch, Geld da", ist der Webhook-Call.

Diese Lektion erledigt drei Dinge: Webhook-URL aus dem Theme holen, im Stripe-Dashboard den Endpoint anlegen, Signing Secret ins Theme eintragen.

Was ein Webhook überhaupt ist

Ein Webhook ist eine automatische HTTP-Anfrage, die Stripe an eine URL auf deinem Blog schickt, sobald etwas Interessantes passiert — z. B. „eine Zahlung ist durchgegangen". Stripe ruft serverseitig die hinterlegte URL auf und schickt die Kaufdaten mit. Dein Blog nimmt den Aufruf entgegen, prüft die Signatur und legt den Kauf in der eigenen Datenbank ab.

Die Webhook-URL aus dem Theme holen

Die URL, die du bei Stripe hinterlegen musst, zeigt das Theme passend für deine Domain an. Unter Design → Downloads → Einrichtung runterscrollen bis „Schritt 3: Webhook einrichten". Dort steht in einem grauen Kasten:

https://deineblog.de/wp-json/bap/v1/downloads/webhook

Wichtig ist der letzte Teil /wp-json/bap/v1/downloads/webhook — das ist die REST-Route, die das Theme für diesen Zweck registriert. Tipp sie niemals frei ab, sondern kopier sie direkt aus dem Einrichtungs-Tab.

Im Stripe-Dashboard den Endpoint anlegen

Im Stripe-Dashboard links auf Developers → Webhooks. Testmodus-Schalter oben rechts muss an sein — ein Webhook aus dem Testmodus existiert im Live-Modus nicht. Oben rechts Add endpoint klicken.

Stripe öffnet ein Formular:

1. Endpoint URL — die Zeile aus dem Theme-Tab einfügen
2. Description — optional, wir empfehlen Foodblogliebe Theme — Digital Downloads
3. Events to send — gleich dazu mehr

Für die Events klickst du auf Select events. Stripe blendet einen Dialog mit hunderten möglichen Events ein — du brauchst genau drei. Im Suchfeld checkout.session eintippen und diese drei anhaken:

• checkout.session.completed
• checkout.session.async_payment_succeeded
• checkout.session.async_payment_failed

Unten Add events, dann im Hauptformular Add endpoint. Stripe leitet dich auf die Detailseite des frisch angelegten Webhooks um — dort holen wir gleich das Signing Secret.

Warum genau diese drei Events

In vielen Tutorials steht nur „ein Event", weil die meisten Kartenkäufe über genau eines laufen. Der Webhook-Handler im Theme verarbeitet aber drei, und jedes löst ein konkretes Problem:

• checkout.session.completed — Standard-Event für Kartenzahlung, Apple Pay, Google Pay. Etwa 90 % der Käufe.
• checkout.session.async_payment_succeeded — SEPA-Lastschrift und Klarna. Bei beiden passiert die Abbuchung Tage später, Stripe meldet den Abschluss zunächst als „pending" und schickt das zweite Event, wenn die Zahlung wirklich durch ist. Das Theme wartet auf dieses zweite Event, bevor es die Datei verschickt — sonst geht das PDF raus, obwohl das Geld noch nicht da ist.
• checkout.session.async_payment_failed — Gegenstück. SEPA-Lastschrift platzt (Konto nicht gedeckt), oder Klarna lehnt nachträglich ab. Das Theme markiert den Kauf dann als failed.

Andere Events wie payment_intent.succeeded, charge.succeeded oder charge.refunded wählst du nicht aus. Das Theme verarbeitet sie nicht, sie bringen nur Rauschen in deine Stripe-Logs.

Signing Secret kopieren und ins Theme eintragen

Auf der Webhook-Detailseite siehst du oben den Abschnitt Signing secret mit „Click to reveal". Einmal klicken, Stripe zeigt eine Zeichenkette, die mit whsec_ beginnt. Kopier sie komplett.

Zurück in WordPress, Design → Downloads → Einrichtung, Abschnitt „Schritt 3: Webhook einrichten", Feld Webhook Secret. Zeichenkette einfügen, Webhook Secret speichern klicken. Grüner Haken „Gespeichert und lesbar" → alles gut.

Warum das Secret wichtig ist: Die Webhook-URL ist öffentlich erreichbar — sie muss es sein, sonst könnte Stripe sie nicht anfunken. Das heißt aber auch: Theoretisch könnte jeder im Internet einen gefälschten Webhook-Call schicken. Um das zu verhindern, rechnet Stripe über jedem echten Call eine Signatur mit deinem Signing Secret. Das Theme prüft diese Signatur bei jedem Eingang und verwirft jeden Call, dessen Signatur nicht stimmt. Falsches Secret gespeichert heißt also: Jeder legitime Stripe-Call wird mit 403 abgelehnt, und dein Blog verhält sich genauso, als gäbe es gar keinen Webhook.

Schnell-Check: feuert der Webhook?

Den kompletten Kauf-Flow testen wir in Lektion 05. Einen kurzen Funktions-Check kannst du aber schon jetzt direkt aus Stripe machen.

Auf der Webhook-Detailseite oben rechts Send test webhook klicken, im Dropdown checkout.session.completed wählen, bestätigen. Stripe schickt einen künstlichen Test-Event und zeigt die Antwort deines Blogs an. Im Reiter Events soll der Eintrag mit Status 200 OK erscheinen.

Andere Antworten bedeuten:

• 403 Forbidden — Signing Secret stimmt nicht. Neu aus Stripe kopieren, neu ins Theme einfügen, speichern, Test wiederholen.
• 404 Not Found — URL zeigt nicht auf die WordPress-REST-Route. URL aus dem Einrichtungs-Tab erneut kopieren.
• 500 Internal Server Error mit no_webhook_secret — Secret noch gar nicht gespeichert.

Der Test-Event legt keinen echten Kauf in der Datenbank an, weil die Order-ID künstlich ist — Stripe bekommt eine 400-Antwort mit unknown_order zurück, wenn die Signatur gültig war. Das ist hier genau richtig, kein Fehler. Uns interessiert nur: Haben Stripe und Blog grundsätzlich miteinander gesprochen.

Webhook ist nicht Resend

Ein Punkt, der gern durcheinandergeht: Der Resend-Endpoint (/wp-json/bap/v1/downloads/resend) ist kein Stripe-Webhook. Er ist ein Selbstbedienungs-Feature für Käuferinnen, die ihre Mail nicht bekommen haben, und wird nicht in Stripe konfiguriert. Details dazu in Lektion 06.

Kurz: Webhook = Stripe funkt dem Blog zu. Resend = Käuferin bittet den Blog um eine neue Mail.

Was jetzt steht und was Lektion 05 bringt

Nach dieser Lektion hat dein Theme alles für einen echten Kauf: Stripe-Keys (Lektion 02), Produkt mit price_... ID und Datei (Lektion 03), Webhook-Endpoint in Stripe mit den drei Events, Signing Secret im Einrichtungs-Tab. Der Einrichtungs-Tab zeigt in der Statusliste grüne Haken bei „Stripe-Keys", „Webhook" und idealerweise auch „E-Mail-Zustellung".

In Lektion 05 drücken wir zum ersten Mal den Buy-Button, bezahlen mit der Testkarte und schauen, ob die Mail ankommt.