Kurzantwort
Die meisten echten Apps sind nicht in sich geschlossen — sie müssen eine Karte über Stripe belasten, eine SMS über Twilio verschicken oder in dem Moment Bescheid bekommen, in dem eine Zahlung durchgeht. Das bedeutet zwei Dinge: deine App ruft andere Dienste auf (ausgehende API-Aufrufe), und andere Dienste rufen zurück in deine App (eingehende Webhooks). Bringst du die Richtung, die Auth und die Retry-Logik durcheinander, lieferst du etwas, das in einer Demo funktioniert und beim ersten Mal bricht, wenn Stripe um zwei Uhr nachts einen fehlgeschlagenen Webhook erneut zustellt.
Warum "einfach einen API-Aufruf hinzufügen" der Punkt ist, an dem die meisten Integrationen scheitern
Ein ausgehender API-Aufruf ist die einfache Hälfte. Du triffst Stripes Endpunkt mit einem Secret Key, bekommst eine Antwort, fertig. Die schwierige Hälfte ist die eingehende Seite — ein Webhook ist Stripe (oder Slack oder Twilio oder HubSpot), das ungefragt, nach eigenem Zeitplan und manchmal zweimal für dasselbe Event in deine App hineinreicht.
Ich habe Teams gesehen, die Webhooks wie einen normalen POST-Request vom eigenen Frontend behandeln: keine Signaturprüfung, keine Idempotenz, kein Timeout-Handling. Das funktioniert einwandfrei, bis ein Kunde eine Zahlung anficht, Stripe dasselbe charge.refunded-Event dreimal feuert, weil dein Endpunkt langsam geantwortet hat, und die Rückerstattung jetzt dreimal in deiner Datenbank verarbeitet wird.
Was auf der eingehenden Seite wirklich passieren muss
Ein Webhook-Handler hat beim ersten Durchlauf genau eine Aufgabe: prüfen, dass es echt ist, schnell bestätigen und die eigentliche Arbeit in die Queue schieben.
Die Signatur prüfen. Jeder große Anbieter signiert seine Payloads — Stripe mit einem Stripe-Signature-Header, GitHub mit X-Hub-Signature-256. Überspringst du diese Prüfung, kann jeder, der deine Endpunkt-URL findet, gefälschte "Zahlung erfolgreich"-Events posten. Das ist bei allem, was Geld oder Account-Status betrifft, nicht optional.
In unter ein paar Sekunden antworten. Anbieter haben kurze Timeouts, bevor sie die Zustellung als fehlgeschlagen werten und erneut versuchen. Wenn dein Handler einen langsamen Datenbank-Write macht, eine Slack-Benachrichtigung verschickt und ein weiteres externes System aktualisiert, bevor er 200 zurückgibt, forderst du doppelte Zustellungen geradezu heraus. Erst bestätigen, dann verarbeiten — entweder in einem Background Job oder einer schlanken Queue.
Von Duplikaten ausgehen. Speichere die Event-ID und prüfe sie vor der Verarbeitung. Diese eine Angewohnheit verhindert fast jeden "Warum ist das zweimal ausgelöst worden"-Bug in Produktion.
Wo das in einer von Greta.sh gebauten App liegt
Wenn Greta.sh eine Full-Stack-App scaffoldet, landen Webhook-Handler als eigene Next.js-API-Routen in einer eigenen Datei, getrennt von deiner regulären App-Logik — app/api/webhooks/stripe/route.ts vermischt sich also nicht mit dem Code, der dein Dashboard verwaltet. Secrets wie das Stripe-Webhook-Signing-Secret werden als Umgebungsvariablen gespeichert, gelangen nie ins Client-Bundle, und die Prisma-gestützte Datenbank gibt dir einen naheliegenden Ort, um Event-IDs für Idempotenz-Prüfungen zu protokollieren. Du verkabelst keine Serverless-Function von Hand und hoffst, dass die Timeout-Config stimmt — es ist schon so strukturiert.
Ausgehende Aufrufe: der Teil, den man unterschätzt
Eine Drittanbieter-API aufzurufen klingt trivial, bis du derjenige bist, der debuggen muss, warum eine Twilio-SMS still fehlgeschlagen ist. Ein paar Dinge zählen mehr, als sie aussehen.
Rate Limits sind real, und Anbieter setzen sie pro API-Key durch, nicht pro Request. Feuert deine App 50 ausgehende Aufrufe in einem Burst ab — etwa weil sie jeden Nutzer in einem Channel benachrichtigt — wirst du gedrosselt, und dein Error-Handling muss einen 429 anders behandeln als einen 500.
Retries brauchen Backoff, keine enge Schleife. Ein fehlgeschlagener Aufruf an einen Zahlungsdienstleister sollte mit steigender Verzögerung erneut versucht werden, nicht fünfmal in einer Sekunde gegen den Endpunkt hämmern.
Secrets gehören immer serverseitig. Ein API-Key in einem clientseitigen Fetch-Aufruf ist ein API-Key, den jeder aus dem Network-Tab seines Browsers auslesen kann. Aufgeschrieben klingt das offensichtlich; es ist trotzdem einer der häufigsten Fehler in schnell gebauten Apps.
Ein einfacher Vergleich: von Hand gebaut vs. gescaffoldet
| Aspekt | Von Hand gebaut | Von Greta.sh gescaffoldet |
|---|---|---|
| Webhook-Signaturprüfung | Du schreibst und testest sie pro Anbieter selbst | Routenstruktur steht bereit; du hängst den Verify-Aufruf des Anbieters ein |
| Secret-Speicherung | Kann versehentlich in Client-Code auslaufen | Umgebungsvariablen, standardmäßig nur serverseitig |
| Umgang mit doppelten Events | Wird oft übersprungen, bis es in Produktion bricht | Prisma-Schema gibt dir von Anfang an einen Ort, um Event-IDs zu protokollieren |
| Background Processing | Eigene Queue oder Cron-Setup | Standard-Next.js-Muster, keine separate Infrastruktur nötig |
| Connector-Katalog | Docs jedes Anbieters einzeln lesen | Vorgefertigte Integrationen in der Connectors-Bibliothek |
Wie das end-to-end aussieht
Angenommen, du baust eine SaaS-App, die Abo-Zahlungen entgegennimmt und den Account eines Nutzers in dem Moment herabstufen muss, in dem eine Zahlung fehlschlägt. Die ausgehende Seite legt das Stripe-Abo an, wenn sich der Nutzer registriert. Die eingehende Seite ist ein Webhook, der auf invoice.payment_failed hört, die Signatur prüft, kontrolliert, ob diese Event-ID schon einmal gesehen wurde, und dann ein Flag in deiner Datenbank umschaltet, das deine App bei jedem Seitenaufruf ohnehin schon abfragt.
Nichts davon ist exotisch. Es sind vielleicht 60 Zeilen Code, sobald man das Muster kennt. Dass es trotzdem schiefgeht, liegt nicht an der Komplexität — es liegt daran, dass die Fehlermodi (doppelte Events, langsame Handler, ausgelaufene Secrets) erst auftauchen, wenn echter Traffic auf den Endpunkt trifft, und dann ist es ein Produktionsvorfall statt eines Code-Review-Kommentars.
Wenn du an so etwas wie einem CRM oder einem breiteren SaaS-Produkt baust, ist genau hier meist der erste Punkt, an dem "läuft auf meinem Rechner" auf die echte Welt trifft — der Moment, in dem deine App mit etwas außerhalb ihrer selbst sprechen muss.
FAQ
Brauche ich eine Message Queue für Webhooks? Bei geringem Volumen nicht. Ein Datenbank-Flag plus eine schnelle Antwort reicht für die meisten Apps. Füge eine Queue hinzu (etwa eine einfache Job-Tabelle, die du pollst), sobald du hunderte Events pro Minute verarbeitest oder die nachgelagerte Arbeit länger als ein paar Sekunden dauert.
Wie teste ich Webhooks lokal? Die meisten Anbieter liefern dafür eine CLI — Stripes stripe listen leitet echte Events an deinen lokalen Server weiter. Bau die Payload-Form nicht von Hand nach; nutze das Tool des Anbieters, damit die Signaturprüfung tatsächlich zur Produktion passt.
Was passiert, wenn mein Endpunkt down ist, während ein Webhook feuert? Seriöse Anbieter versuchen es nach einem Zeitplan erneut (Stripe wiederholt bis zu drei Tage lang). Genau deshalb zählt Idempotenz — der Retry wird irgendwann erfolgreich sein, und dein Handler darf ihn dann nicht doppelt verarbeiten.
Kann ich APIs verbinden, die nicht in einer vorgefertigten Connector-Liste stehen? Ja. Eine Connector-Bibliothek beschleunigt die üblichen Fälle, aber jede REST- oder Webhook-basierte API lässt sich direkt einbinden — es ist einfach ein ausgehender Fetch-Aufruf oder ein eingehender Route-Handler wie jeder andere.
Fazit
Webhooks und Drittanbieter-APIs sind der Punkt, an dem viele "KI-gebaute" Apps beurteilt werden, fair oder nicht — es ist der Teil, der sich mit einer gut aussehenden UI nicht faken lässt. Bekommst du die Signaturprüfungen, die schnellen Bestätigungen und die Idempotenz richtig hin, ist der Rest der Integration reine Verkabelung.