Was ist ein Webhook? So benachrichtigen sich Apps gegenseitig

Ein Webhook ist eine automatische Nachricht, die ein Dienst in dem Moment an deine App sendet, in dem etwas passiert. Wenn die Zahlung eines Kunden erfolgreich ist, sendet Stripe einen Webhook an eine Adresse in deiner App mit der Aussage „Zahlung erfolgreich, hier sind die Details“, und deine App reagiert – markiert die Bestellung als bezahlt, verschickt eine Quittung, schaltet das Konto frei. Kurz gesagt: Eine API ist deine App, die einem anderen Dienst eine Frage stellt; ein Webhook ist der andere Dienst, der deine App anruft, um ihr etwas mitzuteilen.

Warum er beim Bauen mit KI wichtig ist

Sobald deine App Zahlungen annimmt, Formularübermittlungen von einem anderen Tool empfängt oder sich mit Diensten wie GitHub, Shopify oder einem Kalender verbindet, begegnest du Webhooks. Sie sind meist die richtige Methode, um zu erfahren, dass etwas passiert ist – aber genau hier liegen auch die Stellen, an denen mit KI gebaute Apps oft subtil falsch sind:

• Der Endpunkt akzeptiert jede Anfrage, sodass jeder ein gefälschtes Ereignis „Zahlung erfolgreich“ senden kann.
• Die App gewährt Zugriff auf der Weiterleitungsseite des Checkouts statt über den Webhook, sodass Leute, die den Tab früh schließen, nie bekommen, wofür sie bezahlt haben, und Leute, die die Erfolgs-URL finden, es kostenlos erhalten.
• Dasselbe Ereignis kommt zweimal an, und der Kunde bekommt zwei Bestellungen oder zwei E-Mails.

Wenn du weißt, wie Webhooks funktionieren, kannst du die Schutzmaßnahmen von Anfang an einfordern.

Ein Alltagsvergleich: eine Liefer-SMS

Du kannst zwei Wege nutzen, um herauszufinden, ob dein Paket angekommen ist. Du kannst alle zehn Minuten zur Haustür gehen und nachsehen (das ist Polling – deine App fragt wiederholt eine API: „Gibt es etwas Neues?“). Oder der Kurier schickt dir eine SMS, wenn er zugestellt hat (das ist ein Webhook).

Die SMS ist klar besser – solange du ihr vertrauen kannst. Könnte jeder dir eine Nachricht „Paket zugestellt“ schicken, wüsstest du gern, ob sie wirklich vom Kurier stammt. Und wenn dein Handy aus war, als die SMS kam, wäre es gut, wenn der Kurier es später noch einmal versucht. Diese beiden Anliegen – Verifizierung und Wiederholungen – machen den größten Teil dessen aus, was Webhooks knifflig macht.

So funktioniert ein Webhook, Schritt für Schritt

1. Du legst einen Endpunkt im Backend deiner App an: eine URL wie https://yourapp.com/webhooks/stripe, die POST-Anfragen annimmt.
2. Du registrierst diese URL beim Anbieter und wählst aus, welche Ereignisse du willst (zum Beispiel „Checkout abgeschlossen“ und „Abo gekündigt“).
3. Der Anbieter gibt dir ein Signaturgeheimnis. Du speicherst es als Secret auf deinem Server – siehe Umgebungsvariablen und Secrets.
4. Ein Ereignis tritt ein. Der Anbieter sendet eine HTTP-Anfrage an deine URL mit einem JSON-Body, der es beschreibt, plus einem Signatur-Header.
5. Deine App prüft die Signatur, speichert die Ereignis-ID, antwortet schnell mit einem Erfolgscode (200) und erledigt dann die Arbeit.
6. Antwortet deine App nicht mit Erfolg, versuchen viele Anbieter es später erneut.

Signaturen

Eine Signatur beweist, dass die Anfrage vom Anbieter stammt und nicht verändert wurde. Stripe zum Beispiel berechnet einen HMAC (eine Art schlüsselbasierter Fingerabdruck) mit SHA-256 über den Anfrage-Body und einen Zeitstempel, unter Verwendung des Signaturgeheimnisses, und sendet ihn im Header Stripe-Signature. Deine App führt dieselbe Berechnung mit ihrer Kopie des Geheimnisses durch; stimmen die Ergebnisse überein, ist die Anfrage echt. Da auch der Zeitstempel signiert ist, kannst du alte Anfragen ablehnen, die jemand aufgezeichnet und später erneut abspielt – die Bibliotheken von Stripe verwenden laut Dokumentation (Stand September 2026) standardmäßig eine Toleranz von fünf Minuten.

Ein praktisches Detail: Die Signatur wird über den rohen Anfrage-Body berechnet. Wenn dein Framework das JSON parst und neu formatiert, bevor du prüfst, schlägt die Prüfung fehl. Das ist ein sehr häufiger Fehler.

Wiederholungen, Duplikate und Reihenfolge

Anbieter unterscheiden sich, prüfe daher die Dokumentation jedes Anbieters. Stand September 2026:

Die Dokumentation von Stripe sagt außerdem, dass Ereignisse nicht garantiert in der Reihenfolge ankommen, in der sie passiert sind, und dass dasselbe Ereignis gelegentlich mehr als einmal ankommen kann, weshalb sie empfiehlt, Ereignis-IDs zu erfassen.

Die allgemeine Lehre gilt für jeden Anbieter: Ereignisse können verspätet, mehrfach und außer der Reihe ankommen. Dein Handler sollte idempotent sein – die Verarbeitung desselben Ereignisses zweimal hat dieselbe Wirkung wie einmal.

Ein Beispiel: einen bezahlten Kurs freischalten

Du verkaufst einen Online-Kurs. Ein Student klickt auf Kaufen, zahlt auf Stripes gehosteter Checkout-Seite und wird zurück auf deine Website geschickt.

Der fragile Weg: Die „Danke“-Seite schaltet den Kurs frei. Schließt der Student den Browser während der Weiterleitung, hat er bezahlt, aber keinen Zugang. Errät jemand die Danke-URL, bekommt er Zugang ohne zu zahlen.

Der Webhook-Weg:

1. Wenn Stripe die Zahlung bestätigt, sendet es ein Ereignis checkout.session.completed an /webhooks/stripe.
2. Dein Backend prüft die Signatur mit dem Signaturgeheimnis. Schlägt sie fehl, antwortet es mit 400 und tut nichts.
3. Es prüft, ob diese Ereignis-ID bereits verarbeitet wurde. Wenn ja, antwortet es mit 200 und hört auf.
4. Es speichert die Ereignis-ID, antwortet mit 200 und gewährt dann dem Studenten Zugang und verschickt eine Willkommens-E-Mail.
5. Die Danke-Seite sagt nur „Zahlung eingegangen – dein Kurs erscheint gleich“ und prüft den Zugangsstatus des Studenten.

Später sagen andere Webhook-Ereignisse deiner App, dass sie den Zugang entfernen oder pausieren soll, wenn ein Abo gekündigt oder eine Karte abgelehnt wird. So bleiben Abo-Produkte mit der Abrechnung synchron – siehe was SaaS ist und wie du Zahlungen zu deiner App hinzufügst.

Wichtige Begriffe

• Endpunkt: die URL in deiner App, die Webhooks empfängt.
• Ereignis / Payload: was passiert ist und die Daten, die es beschreiben (meist JSON).
• Signaturgeheimnis: das gemeinsame Geheimnis zur Prüfung der Signaturen.
• Idempotent: sicher, mehrfach mit demselben Ergebnis ausgeführt zu werden.
• Polling: eine API wiederholt nach Änderungen fragen, statt auf einen Webhook zu warten.
• Tunnel: ein Werkzeug, das einem Laptop während der Entwicklung eine temporäre öffentliche URL gibt, damit Webhooks ihn erreichen können.

Häufige Fehler und Missverständnisse

• Signaturen nicht prüfen. Die Endpunkt-URL ist kein Geheimnis. Erst die Prüfung macht die Anfrage vertrauenswürdig.
• Vor der Antwort langsame Arbeit erledigen. E-Mails versenden oder PDFs erzeugen, bevor du antwortest, kann zu Timeouts führen, die Wiederholungen auslösen, die zu Duplikaten führen.
• Genau-einmal und in Reihenfolge annehmen. Erfasse Ereignis-IDs und verlass dich nicht auf die Ankunftsreihenfolge.
• Eine Vorschau-URL verwenden. Webhooks brauchen eine stabile, öffentliche Adresse. Private Vorschauen und localhost sind aus dem Internet nicht erreichbar; nutze deine veröffentlichte URL (oder einen Tunnel beim Testen).
• Test- und Live-Geheimnisse vermischen. Anbieter stellen für Test- und Livemodus oft unterschiedliche Signaturgeheimnisse aus. Speichere beide und verwende das richtige.
• Den Payload bei wichtigen Entscheidungen blind vertrauen. Bei folgenreichen Aktionen ist es sinnvoll, nach dem Empfang des Ereignisses den aktuellen Stand über die API des Anbieters abzufragen.

Was du deinen KI-Builder fragen solltest

Füge auf dem Server einen Endpunkt POST /webhooks/stripe hinzu. Prüfe die Stripe-Signatur mit dem rohen Anfrage-Body und dem Geheimnis STRIPE_WEBHOOK_SECRET. Lehne ungültige Signaturen mit 400 ab. Speichere jede Ereignis-ID und überspringe bereits verarbeitete Ereignisse. Antworte schnell mit 200 und behandle dann checkout.session.completed, indem du die Bestellung als bezahlt markierst und die Quittung verschickst. Protokolliere den Ereignistyp. Gewähre keinen Zugriff auf der Erfolgsseite des Checkouts.

Teste es dann: Sende ein Testereignis aus dem Dashboard des Anbieters, sende dasselbe noch einmal und sende eine Anfrage mit einer falschen Signatur. Nur das erste sollte etwas verändern.

Webhooks in Mythex

Mythex betreibt keinen separaten Webhook-Dienst; du bittest den Agenten, einen Webhook-Endpunkt im eigenen Backend deiner App hinzuzufügen, und richtest den Anbieter auf deine veröffentlichte URL, da Webhooks eine öffentliche Adresse brauchen. Das Signaturgeheimnis kommt in deine Projekt-Secrets, und wenn du es in einer Live-App änderst, veröffentlichst du erneut. Das Docs-Rezept Webhooks verarbeiten enthält einen Start-Prompt, und Shop-Vorlagen sind ein guter Ausgangspunkt für Apps, die Zahlungen annehmen.

Fragen