Wie man Stripe Webhooks in CI mit Apidog erfasst und validiert

Ein Kunde bezahlt, Stripe sendet ein `payment_intent.succeeded`-Ereignis an Ihr Backend, und Ihr Endpunkt soll die Bestellung als bezahlt markieren. Dieser letzte Schritt ist derjenige, der stillschweigend abbricht. Der Webhook trifft ein, Ihr Handler wirft einen Fehler, und niemand merkt es, bis ein Support-Ticket eingeht, das besagt: „Ich habe bezahlt, aber mein Konto wird immer noch als unbezahlt angezeigt.“ Sie möchten einen Test in CI, der beweist, dass das Ereignis jedes Mal, wenn Sie etwas veröffentlichen, korrekt empfangen und verarbeitet wurde.

Der knifflige Teil ist, dass ein Webhook ein eingehender HTTP-Aufruf von Stripe an Sie ist, keine Anfrage, die Sie stellen. Die meisten API-Testwerkzeuge sind darauf ausgelegt, eine Anfrage zu senden und die Antwort zu überprüfen, was die entgegengesetzte Form ist. Die Frage lautet also: Wie können Sie etwas überprüfen, das zu einem eigenen Zeitplan in einem CI-Durchlauf ankommt, ohne dass ein Mensch zuschaut? Dieser Leitfaden zeigt Ihnen den ehrlichen, unterstützten Weg, dies mit Apidog zu tun, und er beginnt mit einer Einschränkung, die Sie von vornherein kennen müssen. Wenn Sie zuerst das umfassendere Bild des Testens ereignisgesteuerter Endpunkte wünschen, bereitet unser Leitfaden zum Testen von Webhooks die Bühne, und Stripes eigene Webhook-Dokumentation behandelt das Ereignisbereitstellungsmodell.

Die Einschränkung, die Sie berücksichtigen müssen

Hier ist die tragende Tatsache, die in Apidogs eigener Dokumentation klar dargelegt ist: „Apidog unterstützt das native Abhören von Webhooks nicht.“ Apidog sitzt nicht auf einer öffentlichen URL und fängt Stripes eingehende Anrufe in Echtzeit ab. Wenn Sie gehofft hatten, Stripe auf einen Apidog-Listener zu richten und Ereignisse einzuloggen, existiert dieser Pfad nicht.

Das klingt wie eine Sackgasse. Ist es aber nicht. Es ändert lediglich die Form des Tests. Anstatt den Webhook beim Eintreffen abzufangen, erfassen Sie ihn in Ihrem eigenen Backend, speichern ihn und lassen Apidog dann diesen gespeicherten Datensatz abfragen und darauf überprüfen. Zuerst erfassen, dann validieren. Sobald Sie diese Aufteilung akzeptiert haben, wird der gesamte Workflow unkompliziert und, was wichtig ist, er passt perfekt zu CI, da eine Datenbankabfrage deterministisch und wiederholbar ist.

Wie das Erfassungs-und-Abfrage-Muster aussieht

Das von Apidogs Dokumentation empfohlene Muster besteht aus vier beweglichen Teilen:

Erstellen Sie einen Endpunkt in Ihrem Backend-Dienst, um eingehende Stripe-Webhooks zu erfassen.
Speichern Sie die Webhook-Ereignisdaten in einer Tabelle namens Stripe event logs in Ihrer Datenbank.
Verwenden Sie Apidogs Post-Request Processor, um Ihre Datenbank abzufragen.
Rufen Sie das gespeicherte Webhook-Ereignis ab und validieren Sie es anhand der erwarteten Ergebnisse.

Zwei dieser Schritte befinden sich in Ihrem Code, und zwei in Apidog. Der Erfassungs-Endpunkt und die Protokolltabelle liegen in Ihrer Verantwortung, da sie in Ihrer eigenen Anwendung ausgeführt werden. Apidogs Aufgabe beginnt, sobald das Ereignis in Ihrer Datenbank ist: Es verbindet sich mit dieser Datenbank und liest die Zeile zurück, um zu bestätigen, dass das Ereignis wie erwartet behandelt wurde. Halten Sie diese Trennung klar, und der Rest fügt sich zusammen.

Schritt 1: Erstellen Sie den Erfassungs-Endpunkt

Ihr Backend benötigt eine Route, an die Stripe POSTen kann. Dies ist gewöhnlicher Anwendungscode, keine Apidog-Funktion. Ein minimaler Express-Handler, der die Signatur überprüft und das Ereignis protokolliert, sieht so aus:

import express from "express";
import Stripe from "stripe";

const app = express();
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY);
const endpointSecret = process.env.STRIPE_WEBHOOK_SECRET;

app.post(
  "/webhooks/stripe",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    let event;
    try {
      event = stripe.webhooks.constructEvent(
        req.body,
        req.headers["stripe-signature"],
        endpointSecret
      );
    } catch (err) {
      return res.status(400).send(`Signature check failed: ${err.message}`);
    }

    // Persist the event so a test can read it back later.
    await db.query(
      `INSERT INTO stripe_event_logs (event_id, type, payload, handled_at)
       VALUES ($1, $2, $3, now())
       ON CONFLICT (event_id) DO NOTHING`,
      [event.id, event.type, JSON.stringify(event.data.object)]
    );

    if (event.type === "payment_intent.succeeded") {
      const intent = event.data.object;
      await markOrderPaid(intent.metadata.order_id);
    }

    res.json({ received: true });
  }
);

Zwei Dinge sind hier wichtig. Erstens überprüfen Sie die Stripe-Signatur mit `constructEvent`, bevor Sie etwas vertrauen, was der nicht verhandelbare Sicherheitsschritt für jeden Webhook-Empfänger ist. Wenn Sie die vollständige Begründung für diese Überprüfung wünschen, erklärt unser Walkthrough zur Webhook-Signaturverifizierung, warum ein Vergleich des Roh-Body die einzige sichere Methode ist. Zweitens schreiben Sie das Ereignis in eine Tabelle namens `Stripe event logs`. Diese Zeile wird von Apidog gelesen. Die Klausel `ON CONFLICT DO NOTHING` sorgt für die Idempotenz des Protokolls, da Stripe dasselbe Ereignis mehr als einmal liefern kann.

Schritt 2: Verbinden Sie Ihre Datenbank in der Apidog-Umgebung

Apidog unterstützt die Verbindung zu einer Datenbank in der entsprechenden Umgebung, und diese Verbindung ist es, die dieses gesamte Muster zum Funktionieren bringt. Richten Sie eine Datenbankverbindung für die Umgebung ein, auf die Ihr CI-Lauf abzielt, sei es ein Staging-Postgres oder eine dedizierte Testdatenbank. Sobald die Verbindung hergestellt ist, kann ein Testschritt SQL-Abfragen dagegen ausführen und echte Zeilen zurückziehen.

Passen Sie die Verbindung an die Umgebung an, die Sie testen. Ein Test, der gegen Staging läuft, sollte die Staging-Datenbank abfragen, sodass das Ereignis, das Ihr Test auslöst, das Ereignis ist, das Ihr Test liest. Nicht übereinstimmende Umgebungen sind der häufigste Grund, warum ein funktionierender Erfassungs-Endpunkt die Überprüfung dennoch fehlschlagen lässt.

Schritt 3: Fügen Sie einen Post-Request Processor hinzu, um das Protokoll abzufragen

Das ist der Kern der Sache. Der `Post-Request Processor` ist die Apidog-Funktion, die Ihre Datenbank abfragt und das protokollierte Webhook-Ereignis innerhalb eines Tests validiert. Sie fügen ihn einer Anfrage in Ihrem Testszenario hinzu. Nachdem die Anfrage ausgeführt wurde, führt der Prozessor Ihr SQL aus, liest das gespeicherte Ereignis und ermöglicht es Ihnen, das Ergebnis zu überprüfen.

Ein realistischer Ablauf für den Fall `payment_intent.succeeded`:

Ihr Testszenario löst die Zahlung aus. Dies könnte eine Anfrage sein, die einen Zahlungszweck erstellt und ihn im Stripe-Testmodus bestätigt, oder ein Fixture, das ein bekanntes Testereignis an Ihren Erfassungs-Endpunkt sendet.
Stripe liefert den Webhook an Ihre Route `/webhooks/stripe`, die die Signatur überprüft und eine Zeile in `stripe_event_logs` schreibt.
Ein `Post-Request Processor` im nächsten Schritt fragt diese Tabelle nach dem Ereignis ab.

Die Abfrage, die der Prozessor ausführt, ist einfaches SQL:

SELECT event_id, type, payload, handled_at
FROM stripe_event_logs
WHERE type = 'payment_intent.succeeded'
ORDER BY handled_at DESC
LIMIT 1;

Sie überprüfen dann die zurückgegebene Zeile. Der Test ist erfolgreich, wenn die protokollierten Daten Ihren Erwartungen entsprechen: Der `type` ist `payment_intent.succeeded`, die `event_id` stimmt mit der von Ihnen ausgelösten überein, der `payload`-Betrag entspricht dem von Ihnen abgerechneten Betrag, und `handled_at` ist ausgefüllt, was beweist, dass Ihr Handler tatsächlich ausgeführt wurde und die Zeile kein Platzhalter ist. Rufen Sie das gespeicherte Webhook-Ereignis ab, vergleichen Sie es mit dem erwarteten Ergebnis und lassen Sie die Überprüfung über Erfolg oder Misserfolg entscheiden.

Da die Zustellung von Webhooks nicht sofort erfolgt, geben Sie dem Ereignis einen Moment Zeit, um anzukommen, bevor Sie es abfragen. Ein kleiner Verzögerungsschritt oder eine Abfrageschleife, die die Abfrage einige Male wiederholt, bevor sie fehlschlägt, verhindert, dass der Test mit der Stripe-Zustellung in Konflikt gerät. Dies ist der einzige Punkt, an dem die asynchrone Natur von Webhooks in Ihr Testdesign einfließt, und ein kleines Wiederholungsfenster löst dies sauber.

Ein Hinweis zur Echtzeit-Weiterleitung während der lokalen Entwicklung

Das Muster "Erfassen-und-Abfragen" ist für CI konzipiert, wo eine Datenbank und ein gespeicherter Datensatz genau das sind, was Sie wollen. Die lokale Entwicklung ist eine andere Situation. Wenn Sie den Handler auf Ihrem Laptop schreiben, kann Stripe `localhost` nicht direkt erreichen, daher benötigen Sie etwas, das Ereignisse in Echtzeit an Ihre Maschine weiterleitet.

Dafür verweist Apidogs Dokumentation auf einen Webhook-Relay-Dienst und nennt die Stripe CLI und Ngrok als Beispiele. Die Stripe CLI kann Ereignisse abhören und direkt an Ihren lokalen Port weiterleiten:

stripe listen --forward-to localhost:3000/webhooks/stripe

Das gibt Ihnen Live-Ereignisse, während Sie den Handler erstellen. Ngrok macht dasselbe, indem es Ihren lokalen Port auf einer öffentlichen URL freigibt, die Sie als Stripe-Endpunkt registrieren. Verwenden Sie diese für den inneren Entwicklungszyklus und verlassen Sie sich dann auf den Datenbank- plus `Post-Request Processor`-Flow für die Überprüfungen, die in Ihrer Pipeline ausgeführt werden. Die beiden ergänzen sich: Relay zum Erstellen, Erfassen-und-Abfragen zum Beweisen.

Verwechseln Sie dies nicht mit Apidogs nativer Webhook-Funktion

Apidog hat tatsächlich eine Funktion, die buchstäblich `Webhook` genannt wird, und es ist leicht anzunehmen, dass Sie damit Stripe-Ereignisse abfangen. Das ist aber nicht der Fall, und eine Verwechslung wird Sie einen Nachmittag kosten. Die native `Webhook`-Funktion dient dazu, einen ausgehenden Webhook zu definieren und zu dokumentieren, d.h. einen HTTP-Endpunkt, den Ihr eigenes System aufruft, wenn ein Ereignis auftritt. Das System initiiert den Aufruf an eine externe URL, was das Gegenteil eines regulären Endpunkts ist, bei dem Clients Sie aufrufen. Es wird verwendet, um Zustandsänderungsbenachrichtigungen und asynchrone Aufgabenresultate in Ihren API-Dokumenten zu beschreiben, nicht um eingehende Anrufe von Stripe zu empfangen.

Wenn Sie einen Ihrer eigenen ausgehenden Webhooks dokumentieren möchten, ist der Ablauf kurz:

Klicken Sie auf das `+`-Symbol in der linken Seitenleiste.
Wählen Sie `New Other Protocol APIs` und dann `Webhook`.
Füllen Sie die erforderlichen Felder aus: `Request Method` (typischerweise POST), einen `Webhook Name`, eine optionale `Debug URL` (nur zum Testen) und `Other Info` für den Anfragetext, Header und die Konfiguration.
Klicken Sie auf `Save`.

Um es auszuprobieren, geben Sie eine URL in das Feld `Debug URL` ein und klicken Sie auf `Send`, um den Webhook-Aufruf zu simulieren. Eine wichtige Einschränkung: Die `Debug URL` ist nur für Tests und wird nicht in Ihrer veröffentlichten Dokumentation oder Ihrem OpenAPI-Export angezeigt. Für eine umfassendere Behandlung des Entwurfs und der Dokumentation von Event-Callbacks erklärt unser Artikel über Webhooks im API-Design, wo sie hingehören. Die Kurzversion für diesen Artikel: Die native `Webhook`-Funktion definiert Ihre ausgehenden Ereignisse, und das Muster "Erfassen-und-Abfragen" validiert die eingehenden von Stripe. Halten Sie die beiden in getrennten mentalen Schubladen.

Variationen und Härtung

Sobald die grundlegende Überprüfung funktioniert, machen ein paar Verfeinerungen sie produktionsreif. Überprüfen Sie erstens mehr als nur den Ereignistyp. Überprüfen Sie die `event_id` End-to-End, damit Sie wissen, dass genau das Ereignis, das Sie ausgelöst haben, auch das validierte ist und nicht ein Überbleibsel eines früheren Laufs. Kürzen oder beschränken Sie die `stripe_event_logs`-Tabelle pro Testlauf, wenn sich Ereignisse ansammeln.

Zweitens, testen Sie die Fehlerpfade. Lösen Sie ein Ereignis aus, das Ihr Handler ablehnen sollte, z.B. eine fehlerhafte Signatur oder einen unerwarteten Typ, und stellen Sie sicher, dass kein `handled_at`-Zeitstempel geschrieben wird. Eine Webhook-Testsuite, die nur den positiven Fall prüft, verpasst die Fälle, die Sie tatsächlich um 2 Uhr morgens wecken. Unsere Hinweise zu Best Practices für Zahlungs-Webhooks behandeln die Idempotenz und das Wiederholungsverhalten, die in diese Tests einfließen sollten.

Drittens, halten Sie die Überprüfung eng an der geschäftlichen Bedeutung, nicht nur an der Zustellung. „Das Ereignis ist eingetroffen“ ist schwächer als „die Bestellung wurde bezahlt“. Wenn Ihr Handler eine `orders`-Tabelle aktualisiert, fügen Sie eine zweite Abfrage hinzu, die bestätigt, dass sich der nachgelagerte Zustand geändert hat, sodass der Test die gesamte Kette und nicht nur den Protokolleintrag beweist.

Sie können dies auch über das Merge-Gate hinausführen. Sobald das Szenario in Apidog gespeichert ist, planen Sie es so, dass es regelmäßig ausgeführt wird, damit ein fehlerhafter Webhook-Handler auch zwischen den Bereitstellungen aufgedeckt wird. Unser Leitfaden zum Planen von API-Tests in Apidog zeigt, wie Sie dieselbe Validierung zeitgesteuert ausführen können.

Automatisieren Sie den Workflow mit der Apidog CLI

Alles oben Genannte zahlt sich aus, wenn es unbeaufsichtigt läuft, und hier kommt die Apidog CLI ins Spiel. Dies ist von Natur aus eine CI-Geschichte, daher ist die Einbindung des gespeicherten Szenarios in Ihre Pipeline der natürliche Abschluss. Installieren Sie die CLI und authentifizieren Sie sich mit Ihrem Token:

npm install -g apidog-cli
apidog login --with-token <YOUR_ACCESS_TOKEN>

Führen Sie dann Ihr gespeichertes Webhook-Validierungsszenario unbeaufsichtigt gegen die Umgebung aus, deren Datenbank die Ereignisprotokolle enthält:

apidog run --access-token $APIDOG_ACCESS_TOKEN -t <SCENARIO_ID> -e <ENV_ID> -r cli

Hier ist `-t` die ID des Testszenarios, `-e` die ID der Umgebung und `-r` wählt den Reporter aus. Verwenden Sie `-r html,cli`, wenn Sie neben der Konsolenausgabe für Ihre CI-Artefakte einen durchsuchbaren Bericht wünschen. Das Szenario enthält den `Post-Request Processor` und seine Datenbankabfrage, sodass ein einziger Befehl den Ablauf auslöst, die Zeile `stripe_event_logs` liest und einen Exit-Code ungleich Null zurückgibt, wenn die Überprüfung fehlschlägt, was genau das ist, was eine Pipeline benötigt, um einen Merge zu steuern. Der Apidog CLI Installationsleitfaden behandelt die Token-Einrichtung, und unser CI/CD-Pipeline-Walkthrough zeigt die vollständige GitHub Actions-Integration rund um diesen Befehl.

Häufig gestellte Fragen

Kann Apidog einen Stripe-Webhook direkt empfangen? Nein. Apidogs Dokumentation besagt klar, dass es „das native Abhören von Webhooks nicht unterstützt“. Sie erfassen das Ereignis in Ihrem eigenen Backend-Endpunkt, speichern es in einer Datenbank, und Apidog liest es mit einem `Post-Request Processor` zurück. Für die Echtzeit-Weiterleitung während der lokalen Entwicklung verwenden Sie stattdessen ein Relay wie die Stripe CLI oder Ngrok.

Wo finden die Überprüfungen tatsächlich statt? Innerhalb des `Post-Request Processor`-Schritts einer Anfrage in Ihrem Testszenario. Er fragt Ihre `Stripe event logs`-Tabelle über die in der Umgebung konfigurierte Datenbankverbindung ab, ruft das gespeicherte Ereignis ab und vergleicht es mit Ihren erwarteten Werten. Der Test ist erfolgreich, wenn die protokollierten Daten übereinstimmen.

Benötige ich einen kostenpflichtigen Plan für den Datenbankvalidierungs-Workflow? Apidogs Dokumentation für diesen Workflow erwähnt keine Einschränkungen durch Pläne, daher wird dieser Leitfaden keine erfinden. Die ehrliche Antwort ist, die aktuellen Plan Details auf der Preisgestaltungsseite zu überprüfen. Sie können Apidog herunterladen und ein Testprojekt einrichten, um den Post-Request Processor und die Datenbankverbindung der Umgebung selbst zu sehen.

Wie gehe ich mit der Verzögerung zwischen Auslösung und Zustellung um? Die Webhook-Zustellung erfolgt nicht sofort, daher fügen Sie eine kurze Wartezeit oder eine Abfragewiederholung vor der Abfrage hinzu, damit Ihr Test nicht mit Stripe in Konflikt gerät. Ein paar Wiederholungen über ein paar Sekunden sind normalerweise ausreichend. Wenn Sie neu darin sind, asynchrone Endpunkte zu überprüfen, beginnen Sie mit dem allgemeinen Leitfaden zum Testen von Webhooks, bevor Sie die Stripe-Spezifika hinzufügen.

Ist die native Webhook-Funktion hier überhaupt nützlich? Nicht zum Erfassen von Stripe-Ereignissen. Diese Funktion definiert und dokumentiert Ihre eigenen ausgehenden Webhooks, bei denen Ihr System eine externe URL aufruft. Es ist ein Dokumentations- und Design-Tool, getrennt vom hier verwendeten Muster der eingehenden Erfassung und Abfrage. Halten Sie die beiden klar getrennt.

Zusammenfassung

Sie können Stripe nicht auf Apidog zeigen und Ereignisse live abfangen, und das Gegenteil zu behaupten führt zu einem frustrierenden Nachmittag. Der unterstützte Weg ist sauberer, als er zunächst aussieht: Erfassen Sie den Webhook in Ihrem eigenen Endpunkt, protokollieren Sie ihn in einer Tabelle namens `Stripe event logs`, und lassen Sie dann Apidogs `Post-Request Processor` diesen Datensatz abfragen und bestätigen, dass das Ereignis verarbeitet wurde. Verpacken Sie das gespeicherte Szenario in `apidog run` und Ihre Pipeline beweist bei jedem Merge, dass ein echtes Zahlungsereignis Ihre Bestellung auf "bezahlt" setzt. Probieren Sie es kostenlos aus, keine Kreditkarte erforderlich, und setzen Sie eine echte Überprüfung hinter dem Webhook, der am wichtigsten ist.